> ## 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 概述

> 通过单一 GraphQL 端点查询 Ayrshare 支持的社交媒体操作。

GraphQL API 通过单一端点提供 Ayrshare REST 功能中受支持的一个子集。每个公开的字段都会调用与其 REST 对应项相同的底层控制器，因此身份验证、权限、配额和响应数据均遵循 REST 的行为。REST 仍是覆盖范围更广的 API；请使用 schema 或 Explorer 查看 GraphQL 具体支持哪些操作。

它新增的能力是：可以在一个请求中获取多项内容，并且可以直接从 schema 本身了解当前支持的 GraphQL 功能范围，而无需逐页阅读文档。schema 描述了每个受支持的请求字段，以及结构化响应上可用的类型化选择；以 `JSON` 形式返回 REST 响应信封的操作会保留完整的负载。

```
https://api.ayrshare.com/graphql
```

与任何 GraphQL 端点一样，发送一个 `POST` 请求，其 JSON 请求体中包含 `query`。`GET` 和 `DELETE` 会返回 `405 Method Not Allowed`：在 GraphQL 规范中，通过 `GET` 发送查询是可选的，此处不受支持。

<h2 id="your-first-query">
  你的第一个查询
</h2>

```bash theme={"system"}
curl -X POST https://api.ayrshare.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ postHistory(lastDays: 7) }"}'
```

响应与 [REST 历史记录端点](/docs/apis/history/get-history) 返回的 JSON 信封相同，只是包裹在 GraphQL 的 `data` 字段中：

```json theme={"system"}
{
  "data": {
    "postHistory": {
      "history": [
        { "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }
      ],
      "refId": "9d2a7c41f0b8e6d35a1c",
      "count": 1,
      "lastUpdated": "2026-09-24T12:00:00.000Z",
      "nextUpdate": "2026-09-24T12:00:00.000Z"
    }
  }
}
```

<h2 id="asking-for-several-things-at-once">
  一次获取多项内容
</h2>

选择 GraphQL 的理由就在于下面这样的请求，如果使用 REST，则需要四次调用：

```graphql theme={"system"}
{
  history: postHistory(lastDays: 7)
  accounts: user
  comments: comments(id: "abc123")
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}
```

一次往返即可返回全部四项结果。请注意，就计费而言，这是**四个根操作字段和四次 API 调用**，而不是一次。选择嵌套的响应字段不会增加调用次数，请参见[限制与计费](/docs/apis/graphql/limits)。

<h2 id="authentication">
  身份验证
</h2>

与 REST 完全相同。将你的 API Key 作为 bearer token 发送：

```
Authorization: Bearer YOUR_API_KEY
```

如果你的账户使用 User Profile，公开了 `profileKey` 的操作可以通过以下两种方式之一选择配置文件：

<ul class="custom-bullets">
  <li>发送 <code>Profile-Key</code> 作为整个请求的默认值。</li>
  <li>在单个字段上传入 <code>profileKey</code> 以覆盖该默认值，从而让一个请求可以作用于多个配置文件。</li>
</ul>

两者同时存在时，以字段参数为准。账户级字段或仅限主账户的字段不会公开 `profileKey`，并且可能会拒绝 `Profile-Key` header；例如，`createProfile` 必须使用主 API Key，且不能带该 header。请查看每个字段的 schema 定义以了解其作用范围，并参见[管理多个用户](/docs/multiple-users/business-plan-overview)了解 Profile Key 的工作方式。

<h2 id="try-it-without-writing-code">
  无需编写代码即可试用
</h2>

[GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) 是用于浏览当前 schema 的交互式工具。它列出了每个可用的 GraphQL 操作及其参数和描述，会在你输入时自动补全，并可针对你的账户运行查询。

浏览 schema 不需要 API Key：schema 是公开的，就像本文档一样。但运行查询需要 API Key，因为每个操作都要经过与 REST 相同的身份验证。

<h2 id="should-you-use-graphql-or-rest">
  应该使用 GraphQL 还是 REST？
</h2>

REST 仍然是主要接口，我们的大部分文档、[SDK](/docs/packages-guides/overview) 和集成都是围绕它构建的。在以下情况下可以选择 GraphQL：

<ul class="custom-bullets">
  <li>你需要多项互不相关的数据，并希望通过一次往返获取。</li>
  <li>你需要机器可读的操作名称、参数、输入对象、枚举和类型化的响应选择。大多数响应仍为 <code>JSON</code>，以保留完整的 REST 响应信封；<code>createPost</code> 目前返回类型化的 <code>PostResult</code>。</li>
  <li>你正在探索 API，希望无需在多个文档页面之间切换就能了解有哪些功能。</li>
</ul>

在以下情况下请继续使用 REST：

<ul class="custom-bullets">
  <li>你需要上传文件。媒体字节无法通过 GraphQL 请求传输，受支持的方式请参见<a href="/docs/apis/graphql/using-the-api#uploading-media">上传媒体</a>。</li>
  <li>你正在使用我们的某个 <a href="/docs/packages-guides/overview">SDK 或无代码集成</a>，它们使用的是 REST。</li>
  <li>你希望依赖尽可能少。REST 调用只需要一个 HTTP 客户端。</li>
</ul>

两种接口同时受支持，你可以在同一个集成中自由混合使用。

<h2 id="read-next">
  延伸阅读
</h2>

<ul class="custom-bullets">
  <li>[使用 API](/docs/apis/graphql/using-the-api)：查找操作、参数类型以及上传媒体。</li>
  <li>[错误](/docs/apis/graphql/errors)：哪些失败会改变 HTTP 状态码、为什么失败的操作仍返回 HTTP 200，以及如何处理部分成功。</li>
  <li>[限制与计费](/docs/apis/graphql/limits)：查询大小上限以及请求的计数方式。</li>
</ul>