Skip to main content
GraphQL API は、Ayrshare の REST 機能のうちサポートされているサブセットを単一のエンドポイントで公開します。公開されている各フィールドは対応する REST と同じ内部コントローラーを呼び出すため、認証、利用権限、クォータ、レスポンスデータは REST の動作に従います。REST は引き続きより広範な API です。GraphQL がどの操作をサポートしているかを正確に確認するには、スキーマまたは Explorer を使用してください。 GraphQL によって追加されるのは、1 回のリクエストで複数のものを要求できる機能と、ドキュメントを 1 ページずつ読まなくても、現在サポートされている GraphQL の範囲をスキーマ自体から把握できる機能です。スキーマには、サポートされているすべてのリクエストフィールドと、構造化されたレスポンスで利用可能な型付きの選択項目が記述されています。REST のエンベロープを JSON として返す操作は、そのペイロード全体をそのまま保持します。
他の GraphQL エンドポイントとまったく同じように、query を含む JSON ボディを付けて POST を送信します。GET と DELETE は 405 Method Not Allowed を返します。GET によるクエリは GraphQL 仕様ではオプションであり、ここではサポートされていません。

​
最初のクエリ

レスポンスは、REST の履歴エンドポイントが返すものと同じ JSON エンベロープを、GraphQL の data フィールドで包んだものです:

​
複数のものを一度に要求する

GraphQL を使う理由は、REST なら 4 回の呼び出しが必要になる次のようなリクエストです:
1 回のラウンドトリップで 4 つすべてが返されます。ただし、これは 1 回ではなく、4 つのルート操作フィールドであり、課金上は 4 回の API 呼び出しとなる点に注意してください。ネストされたレスポンスフィールドを選択しても呼び出し回数は増えません。制限と課金を参照してください。

​
認証

REST と同じです。API キーを Bearer トークンとして送信します:
アカウントで User Profiles を使用している場合、profileKey を公開している操作では、次の 2 つの方法のいずれかでプロファイルを選択できます:
  • Profile-Key をリクエスト全体のデフォルトとして送信する。
  • 個々のフィールドで profileKey を渡してそのデフォルトを上書きし、1 回のリクエストで複数のプロファイルを操作する。
両方が指定されている場合は、フィールドの引数が優先されます。アカウントレベルまたはプライマリアカウント専用のフィールドは profileKey を公開しておらず、Profile-Key ヘッダーを拒否する場合があります。たとえば、createProfile はそのヘッダーを付けずにプライマリの API キーで使用する必要があります。各フィールドのスコープについてはスキーマ定義を確認し、Profile Key の仕組みについては複数ユーザーの管理を参照してください。

​
コードを書かずに試す

GraphQL Explorer は、現在のスキーマを対話的に閲覧できるブラウザです。利用可能なすべての GraphQL 操作を引数や説明とともに一覧表示し、入力中に自動補完を行い、あなたのアカウントに対してクエリを実行できます。 スキーマの閲覧に API キーは必要ありません。このドキュメントと同様に、スキーマは公開されています。ただし、クエリを実行するには API キーが必要です。すべての操作は REST と同じ認証を通過するためです。

​
GraphQL と REST のどちらを使うべきか

REST は引き続き主要なインターフェースであり、ほとんどのドキュメント、SDK、インテグレーションは REST を中心に構築されています。次のような場合は GraphQL を使用してください:
  • 関連のない複数のデータが必要で、それらを 1 回のラウンドトリップで取得したい場合。
  • 機械可読な操作名、引数、入力オブジェクト、列挙型、型付きのレスポンス選択を利用したい場合。ほとんどのレスポンスは REST のエンベロープ全体を保持するため引き続き JSON ですが、createPost は現在、型付きの PostResult を返します。
  • API を調べていて、ドキュメントのページを行き来せずに何が存在するかを確認したい場合。
次のような場合は REST を使い続けてください:
  • ファイルをアップロードする場合。メディアのバイトデータは GraphQL リクエストでは送信できません。サポートされている方法については メディアのアップロード を参照してください。
  • REST を使用する SDK やノーコードインテグレーション のいずれかを使用している場合。
  • 依存関係を可能な限り最小限にしたい場合。REST 呼び出しに必要なのは HTTP クライアントだけです。
どちらのインターフェースも並行してサポートされており、同じインテグレーション内で自由に組み合わせることができます。
  • API の使用 — 操作の探し方、引数の型、メディアのアップロード。
  • エラー — HTTP ステータスが変わる失敗の種類、失敗した操作でも HTTP 200 が返る理由、部分的な成功の扱い方。
  • 制限と課金 — クエリサイズの上限と、リクエストのカウント方法。