> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL API の使用

> Ayrshare GraphQL API で、操作の検索、引数の型と列挙型の理解、投稿の作成、メディアのアップロードを行う方法。

<h2 id="finding-an-operation">
  操作を探す
</h2>

サポートされている GraphQL サブセットについては、スキーマが正式な情報源です。操作のルート、名前、引数、入力型、列挙値がスキーマに定義されています。説明には使用方法のガイダンスが記載されており、[GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) ではその両方を確認できます。REST のみで利用できる機能については、[REST API リファレンス](/docs/apis/overview)を使用してください。

操作名は、対応する REST エンドポイントに従い、camelCase で命名されています。`GET /history` は `postHistory`、`GET /analytics/social` は `socialAnalytics`、`POST /post` は `createPost` です。

<h2 id="queries-read-mutations-write">
  クエリは読み取り、ミューテーションは書き込み
</h2>

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

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

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

<h2 id="creating-a-post">
  投稿を作成する
</h2>

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

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

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

```graphql theme={"system"}
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 }
  }
}
```

投稿は、あるソーシャルネットワークでは成功し、別のソーシャルネットワークでは失敗することがあります。これはリクエストの失敗ではありません。[エラー](/docs/apis/graphql/errors#partial-success-on-multi-network-posts)を参照してください。

<h2 id="argument-types">
  引数の型
</h2>

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

<h3 id="enums">
  列挙型
</h3>

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

```graphql theme={"system"}
{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }
```

`"instagram"` ではありません。サーバーは、受け付けた各列挙値を内部の REST コントローラーが期待する正確な値にマッピングします。多くの場合は小文字の文字列ですが、常にそうとは限りません。無効な列挙値は、操作の実行前に GraphQL の検証段階で拒否されるため、入力ミスによるコストは発生しません。

一部の引数は、操作間で名前が同じでも受け付ける値が異なります。これはエンドポイントが実際に異なるためです。`reviews(platform:)` は `GMB` と `FACEBOOK` のみを受け付けます。レビューがあるソーシャルネットワークはこの 2 つだけだからです。クライアントの自動補完では、操作ごとに正しい値の集合が表示されます。

<h3 id="the-json-scalar">
  JSON スカラー
</h3>

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

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

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

<h3 id="optional-arguments-and-nulls">
  オプション引数と null
</h3>

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

<h2 id="reading-responses">
  レスポンスを読む
</h2>

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

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

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

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

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

<h2 id="uploading-media">
  メディアのアップロード
</h2>

**メディアのバイトデータは GraphQL リクエストでは送信できません。** GraphQL リクエストは 64 KB の制限内に収まる単一の JSON ドキュメントであるため、ファイルを受け付けるフィールドはありません。また、画像をクエリ内で base64 エンコードすると、サムネイルより大きいものはこの制限を超えてしまいます。

サポートされている方法はこの問題を完全に回避し、バイトデータが直接ストレージに送られるため、いずれにしても API 経由でアップロードするよりも高速です:

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

   ```graphql theme={"system"}
   mutation { mediaUploadUrl(contentType: "image/jpeg") }
   ```

2. 返された JSON から `data.mediaUploadUrl.uploadUrl`、`accessUrl`、`contentType` を読み取ります。

3. ファイルを Ayrshare API ではなく **`uploadUrl` に直接** `PUT` し、リクエストの `Content-Type` ヘッダーには返された `contentType` を設定します。

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

   ```graphql theme={"system"}
   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 のアップロードエンドポイント](/docs/apis/media/upload-media)を引き続き使用し、得られた URL を GraphQL から参照することもできます。2 つのインターフェースは同じメディアライブラリを共有しています。

<h2 id="read-next">
  次に読む
</h2>

<ul class="custom-bullets">
  <li>[エラー](/docs/apis/graphql/errors) — HTTP ステータスコード、エラーの形式、部分的な成功。</li>
  <li>[制限と課金](/docs/apis/graphql/limits) — クエリサイズの上限と、リクエストのカウント方法。</li>
</ul>