GraphQL API の使用

操作を探す

サポートされている GraphQL サブセットについては、スキーマが正式な情報源です。操作のルート、名前、引数、入力型、列挙値がスキーマに定義されています。説明には使用方法のガイダンスが記載されており、GraphQL Explorer ではその両方を確認できます。REST のみで利用できる機能については、REST API リファレンスを使用してください。操作名は、対応する REST エンドポイントに従い、camelCase で命名されています。GET /history は postHistory、GET /analytics/social は socialAnalytics、POST /post は createPost です。

クエリは読み取り、ミューテーションは書き込み

クエリは、こちら側で何も変更しない読み取りと検証です。ミューテーションは、公開や状態の変更、処理の開始、メールの送信を行います。どちらのルートになるかは、REST の HTTP メソッドや呼び出しのコストでは決まりません:

validatePost は、投稿を公開せずにチェックします。
validateMedia は、メディア URL にアクセスできるかをチェックします。
generatePost は、こちら側で何も変更しないためクエリです。ただし API 呼び出しとしてカウントされ、毎回異なるテキストを返すため、クライアントのキャッシュや自動再取得によって気付かないうちに繰り返し実行されないようにしてください。
mediaUploadUrl は、アカウント用のアップロード URL を作成するためミューテーションです。
linkAnalytics は、メールでのレポート送信をリクエストできるためミューテーションです。
userBatch は、エクスポートジョブを開始するためミューテーションです。

サポートされている各操作のルートは、Explorer またはスキーマで確認してください。

投稿を作成する

createPost は単一の input 引数を受け取るため、投稿全体が 1 つのオブジェクトになります:

mutation {
  createPost(input: {
    post: "Hello from GraphQL"
    platforms: [LINKEDIN]
    idempotencyKey: "post-2026-09-01-001"
  }) {
    status
    id
  }
}

入力は、ドキュメント化されている REST の投稿エンドポイントを反映しており、ソーシャルネットワークごとのオプションオブジェクトや、複数の JSON 形式を受け付ける REST の形式も含まれます:

mutation {
  createPost(input: {
    post: "New video"
    platforms: [YOUTUBE]
    mediaUrls: ["https://example.com/video.mp4"]
    idempotencyKey: "youtube-video-001"
    youTubeOptions: {
      title: "My video"
      visibility: PUBLIC
    }
  }) {
    status
    id
    postIds { platform postUrl }
  }
}

投稿は、あるソーシャルネットワークでは成功し、別のソーシャルネットワークでは失敗することがあります。これはリクエストの失敗ではありません。エラーを参照してください。

引数の型

ほとんどの引数は、通常の文字列、数値、ブール値です。知っておくべきケースが 3 つあります。

列挙型

サポートされる値の集合が決まっている文字列引数の多くは GraphQL の列挙型であり、引用符なし・大文字で記述します:

{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }

"instagram" ではありません。サーバーは、受け付けた各列挙値を内部の REST コントローラーが期待する正確な値にマッピングします。多くの場合は小文字の文字列ですが、常にそうとは限りません。無効な列挙値は、操作の実行前に GraphQL の検証段階で拒否されるため、入力ミスによるコストは発生しません。一部の引数は、操作間で名前が同じでも受け付ける値が異なります。これはエンドポイントが実際に異なるためです。reviews(platform:) は GMB と FACEBOOK のみを受け付けます。レビューがあるソーシャルネットワークはこの 2 つだけだからです。クライアントの自動補完では、操作ごとに正しい値の集合が表示されます。

JSON スカラー

一部の引数は、特定の型ではなく JSON として型付けされています。これは、値が正当に複数の形式を取り、単一の GraphQL 型では正確に表現できない場合です:

explainError(code:) は 215 と “215” のどちらも受け付けます。お客様がエラーコードを両方の形式で保持しているためです。
createPost(input:) は、post や mediaUrls などのフィールドに JSON を使用します。これらは共通の値にも、プラットフォームごとのオブジェクトにもなり得るためです。
createAutomation(triggers:, actions:) は、各要素の type によってフィールドが変わる配列を受け取ります。
boostFacebookPost(interests:) は、Meta のインタレスト ID を文字列または数値で受け付けます。

対応する REST のボディで送信するのと同じ値を渡してください。JSON 引数は抜け道ではありません。リゾルバーはディスパッチ前に値を検証するため、無効な値は検証エラーを返し、API 呼び出しを消費しません。

オプション引数と null

オプション引数や入力オブジェクト内のオプションフィールドでは、明示的な null は省略として扱われます。リスト型が許可している場合、リスト内の null 要素は保持されます。

レスポンスを読む

ほとんどの操作は、REST のレスポンスエンベロープ全体を含む JSON スカラーを返すため、サブフィールドなしでルートフィールドを選択します。createPost は現在、型付きの PostResult を返すため、そのフィールドを選択します:

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    id
    postIds { platform postUrl }
    errors { platform message code }
  }
}

PostResult などの型付きレスポンス型には、変更されていない REST レスポンス全体を含む raw: JSON! も含まれます:

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    raw
  }
}

raw は恒久的なフィールドです。REST レスポンスに新しいフィールドが追加された場合に、こちらで型付けが追いつくまでの間も GraphQL からアクセスできなくなることがないように用意されています。型付きフィールドで公開されていないものが必要な場合は、raw を要求してください。

メディアのアップロード

メディアのバイトデータは GraphQL リクエストでは送信できません。 GraphQL リクエストは 64 KB の制限内に収まる単一の JSON ドキュメントであるため、ファイルを受け付けるフィールドはありません。また、画像をクエリ内で base64 エンコードすると、サムネイルより大きいものはこの制限を超えてしまいます。サポートされている方法はこの問題を完全に回避し、バイトデータが直接ストレージに送られるため、いずれにしても API 経由でアップロードするよりも高速です:

アップロード URL を要求します:

mutation { mediaUploadUrl(contentType: "image/jpeg") }

返された JSON から data.mediaUploadUrl.uploadUrl、accessUrl、contentType を読み取ります。
ファイルを Ayrshare API ではなく uploadUrl に直接 PUT し、リクエストの Content-Type ヘッダーには返された contentType を設定します。

アップロードが成功したら、createPost.input.mediaUrls に accessUrl を渡します:

mutation {
  createPost(input: {
    post: "With a photo"
    platforms: [INSTAGRAM]
    mediaUrls: ["https://the-returned-access-url"]
    idempotencyKey: "instagram-photo-001"
  }) {
    status
    postIds { platform postUrl }
  }
}

uploadUrl は有効期間の短い書き込み用認証情報として扱い、ログに記録したり公開したりしないでください。accessUrl は投稿の作成時に使用するメディア URL です。 REST のアップロードエンドポイントを引き続き使用し、得られた URL を GraphQL から参照することもできます。2 つのインターフェースは同じメディアライブラリを共有しています。

次に読む

エラー — HTTP ステータスコード、エラーの形式、部分的な成功。
制限と課金 — クエリサイズの上限と、リクエストのカウント方法。

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

操作を探す

クエリは読み取り、ミューテーションは書き込み

投稿を作成する

引数の型

列挙型

JSON スカラー

オプション引数と null

レスポンスを読む

メディアのアップロード

次に読む

​操作を探す

​クエリは読み取り、ミューテーションは書き込み

​投稿を作成する

​引数の型

​列挙型

​JSON スカラー

​オプション引数と null

​レスポンスを読む

​メディアのアップロード

​次に読む

操作を探す

クエリは読み取り、ミューテーションは書き込み

投稿を作成する

引数の型

列挙型

JSON スカラー

オプション引数と null

レスポンスを読む

メディアのアップロード

次に読む