快速入门

GraphQL reporting API帮助广告主和开发者能够从Tapjoy平台访问报告数据。在 GraphQL reporting API 中，您可以在marketing API部分此处中找到广告主用例，并在开发者API示例此处中找到开发者用例。

1. Authentication

要访问 Marketing 或 Publisher API，您首先需要您的 API 密钥。作为 Ad Dashboard 用户，您可以在 https://dashboard.tapjoy.com/reporting/api 找到此密钥。

如果您使用 LTV 平台，则需要 "Marketing API Key"，该密钥可在 LTV 平台上找到。可以通过选择应用程序 -> 设置 -> 应用设置 -> 应用信息 -> API 密钥 -> Marketing API Key来找到此密钥。

API使用标准的二次OAuth2验证对请求进行身份验证。使用 API 密钥请求访问令牌，生成的访问令牌用于针对未来的请求进行身份验证。

您可以在此处找到有关获取访问令牌的指南。

2. GraphQL 入口

API独立的入口：

https://api.tapjoy.com/graphql

无论执行何种操作，该入口都保持不变。

3. 使用GraphQL

获得访问令牌后，即可向 API 发出请求。所有API 的请求，无论您是执行查询还是更新，都通过 HTTP POST 提供 JSON 格式数据。

示例请求：

Raw

Curl

Ruby

POST /graphql
Host: api.tapjoy.com
Authorization: Bearer <OAuth Token>

{
  "query": "query { user { firstName } }"
}

4. 错误处理

使用 API 时可能会遇到几类错误：

服务器/网络错误
身份验证/授权错误
查询语法错误
数据验证错误

为确保您的系统正确集成，您需要考虑您的系统应如何处理这些类别的错误。

下面具体说明每个错误类型出现的场景：

query {
  user {
    firstName
    lastName
  }
}

服务器/网络错误

有时，您可能会遇到 API 无法恢复的服务器/网络错误。在这些情况下，您将收到相应 http 状态代码。例如，如果我们的 API 有问题阻止查询执行，那么您将收到带有 500 状态代码的 HTTP 响应。

处理这种情况的最佳方法是多次重试。

身份验证/授权错误

身份验证/授权错误可能有几个原因：

您的 OAuth 令牌已过期
您的 OAuth 令牌无效
我们的底层身份验证系统出现问题

在这些类型的情况下，您将收到包含以下数据的 HTTP 200 OK 响应：

{
  "errors": [
    {
      "message": "Authentication could not be verified. Please try again later.",
      "code": 403
    }
  ]
}

message - 错误描述
code - 对应于 HTTP 状态码的 GraphQL 状态码

处理这种情况的最佳方法是请求新的访问令牌并重试该请求。

查询语法错误

所有查询和更新都经过预先验证，以保证在语法上是正确的并遵循所描述的数据模式。如果提供的查询未通过所有模式验证，那么您将收到包含以下数据的 HTTP 200 OK 响应：

{
  "errors": [
    {
      "message": "Field 'user' doesn't exist on type 'Query'",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "fields": [
        "query",
        "user"
      ]
    }
  ]
}

message - 错误描述
locations - 语法错误的位置
fields - 受语法错误影响的字段

处理这种情况的最佳方法是参考 API 文档并在Interactive Explorer中测试您的查询。

数据验证错误

尽管您可以提供一个使用所有必需字段正确构建的更新语句，但它仍然可能由于业务验证而失败。例如，假设您是一位广告客户，将您的 AdSet 的出价更改为低于最低值，如下所示：

mutation {
  updateAdSet(input: {
    id: "00000000-0000-0000-0000-000000000000",
    bidding: {amount: 10000}
  }) {
    adSet {
      id
    }
  }
}

在这种情况下，您将收到包含以下数据的 HTTP 200 OK 响应：

{
  "data": {
    "updateAdSet": null
  },
  "errors": [
    {
      "message": "Amount is below the minimum (20000 micros)",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "updateAdSet",
        "input",
        "bidding",
        "amount"
      ],
      "code": 422
    }
  ]
}

message - 错误描述
locations - 验证错误的位置
path - 被确定为无效的字段
code - 对应于 HTTP 状态码的 GraphQL 状态码

处理这种情况的最佳方法是将错误消息与相应的字段一起呈现给用户。

快速入门
1. Authentication
2. GraphQL 入口
3. 使用GraphQL
4. 错误处理