Skip to main content
GraphQL API 通过单一端点提供 Ayrshare REST 功能中受支持的一个子集。每个公开的字段都会调用与其 REST 对应项相同的底层控制器，因此身份验证、权限、配额和响应数据均遵循 REST 的行为。REST 仍是覆盖范围更广的 API；请使用 schema 或 Explorer 查看 GraphQL 具体支持哪些操作。 它新增的能力是：可以在一个请求中获取多项内容，并且可以直接从 schema 本身了解当前支持的 GraphQL 功能范围，而无需逐页阅读文档。schema 描述了每个受支持的请求字段，以及结构化响应上可用的类型化选择；以 JSON 形式返回 REST 响应信封的操作会保留完整的负载。
与任何 GraphQL 端点一样，发送一个 POST 请求，其 JSON 请求体中包含 query。GET 和 DELETE 会返回 405 Method Not Allowed：在 GraphQL 规范中，通过 GET 发送查询是可选的，此处不受支持。

​
你的第一个查询

响应与 REST 历史记录端点 返回的 JSON 信封相同，只是包裹在 GraphQL 的 data 字段中：

​
一次获取多项内容

选择 GraphQL 的理由就在于下面这样的请求，如果使用 REST，则需要四次调用：
一次往返即可返回全部四项结果。请注意，就计费而言，这是四个根操作字段和四次 API 调用，而不是一次。选择嵌套的响应字段不会增加调用次数，请参见限制与计费。

​
身份验证

与 REST 完全相同。将你的 API Key 作为 bearer token 发送：
如果你的账户使用 User Profile，公开了 profileKey 的操作可以通过以下两种方式之一选择配置文件：
  • 发送 Profile-Key 作为整个请求的默认值。
  • 在单个字段上传入 profileKey 以覆盖该默认值，从而让一个请求可以作用于多个配置文件。
两者同时存在时，以字段参数为准。账户级字段或仅限主账户的字段不会公开 profileKey，并且可能会拒绝 Profile-Key header；例如，createProfile 必须使用主 API Key，且不能带该 header。请查看每个字段的 schema 定义以了解其作用范围，并参见管理多个用户了解 Profile Key 的工作方式。

​
无需编写代码即可试用

GraphQL Explorer 是用于浏览当前 schema 的交互式工具。它列出了每个可用的 GraphQL 操作及其参数和描述，会在你输入时自动补全，并可针对你的账户运行查询。 浏览 schema 不需要 API Key：schema 是公开的，就像本文档一样。但运行查询需要 API Key，因为每个操作都要经过与 REST 相同的身份验证。

​
应该使用 GraphQL 还是 REST？

REST 仍然是主要接口，我们的大部分文档、SDK 和集成都是围绕它构建的。在以下情况下可以选择 GraphQL：
  • 你需要多项互不相关的数据，并希望通过一次往返获取。
  • 你需要机器可读的操作名称、参数、输入对象、枚举和类型化的响应选择。大多数响应仍为 JSON，以保留完整的 REST 响应信封；createPost 目前返回类型化的 PostResult。
  • 你正在探索 API，希望无需在多个文档页面之间切换就能了解有哪些功能。
在以下情况下请继续使用 REST：
  • 你需要上传文件。媒体字节无法通过 GraphQL 请求传输，受支持的方式请参见上传媒体。
  • 你正在使用我们的某个 SDK 或无代码集成，它们使用的是 REST。
  • 你希望依赖尽可能少。REST 调用只需要一个 HTTP 客户端。
两种接口同时受支持，你可以在同一个集成中自由混合使用。
  • 使用 API：查找操作、参数类型以及上传媒体。
  • 错误：哪些失败会改变 HTTP 状态码、为什么失败的操作仍返回 HTTP 200，以及如何处理部分成功。
  • 限制与计费：查询大小上限以及请求的计数方式。