Reporting API最佳实践

上次更新时间：2024年12月11日

Reporting API允许广告主和开发者使用GraphQL查询语言访问Tapjoy平台的报告数据并管理其Offerwall内容。有关GraphQL的更多信息，请访问GraphQL的官方网站。

API Explorer 可用于协助构建查询。点击左上角的书本图标，展开文档浏览器，查找可在查询中使用的字段和指标的信息。

image_title

1. API 端点

Reporting API 有一个端点：

https://api.tapjoy.com/graphql

无论执行什么操作，该端点都保持不变。

2. 与 API 通信

获得访问令牌后，即可向API发出请求。要创建API请求，无论您执行的是查询还是变更，都需要通过HTTP POST提供JSON编码的主体。

示例请求：

Raw

Curl

Ruby

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

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

3. 处理错误

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

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

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

注意：Reporting 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 文档，并在交互式浏览器中测试您的查询。

数据验证错误

即使您提供的变更已正确构建，并包含所有必需字段，它仍然可能由于业务验证而失败。例如，假设您是一位广告客户，将出价更改为低于广告集的最低出价，如下所示：

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 状态码

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

4. 限制

Reporting API 设有某些保护措施，以防止过度或滥用API调用。如果您的集成超出了现有限制，请联系您的Tapjoy客户经理或支持人员，了解如何优化集成或如何提高限制。

以下示例以广告主为例进行演示，但也适用于开发者集成。

数据保留

Reporting API可以访问过去两年的数据。

分页

查询分页类型时，客户端必须：

提供 first 或 last 参数
单页节点数不得超过 100 个

如果超过最大值，结果将被截断，因此请求的first / last参数将被忽略。

For example:

{
  advertiser {
    adSets(first: 50) {
      edges {
        node {
          id
          name

          ads(first: 50) {
            edges {
              node {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

在上面的查询中，这将返回最多 50 个广告集，每个广告集最多包含 50 个广告。

为了对集合进行分页，您必须提供 after 或 before 参数来控制页面的起始位置。例如：

{
  advertiser {
    adSets(first: 50, after: "Mg==") {
      edges {
        node {
          id
          name
        }
      }

      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

在上面的查询中，它将返回最多50个广告，从光标位置“Mg==”开始。该位置由上一个查询返回的 endCursor 确定。当 hasNextPage 为 false 时，分页应视为完成。

您可以在 GraphQL 官方网站上了解更多关于分页的信息。

调用复杂度

要通过架构验证，所有Marketing API调用的“调用次数”不得超过10,000 次。在本例中，“调用”指的是对资源的请求。由于 GraphQL 允许将多个调用合并为一个查询，因此API会在执行查询之前预先计算出单个查询的总调用次数。

调用次数大致相当于从结果中选择的资源数量（例如，广告系列、广告组、广告、应用、洞察等）。

我们再考虑一下上面的例子：

{
  advertiser {
    adSets(first: 50) {     # <= 50 calls
      edges {
        node {
          id
          name

          ads(first: 50) {  # <= 50 calls
            edges {
              node {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

在此示例中，客户一次最多请求50个ad sets；对于每个ad set，他们最多请求该广告组中的50个ad。

要计算总调用次数，请执行以下操作：

50      = 50 ad sets
+
50 x 50 = 2500 ads
        = 2550 calls

目前，每小时调用次数没有限制。不过，未来可能会有所调整。

insights复杂度

在任何级别查询报告insights都会产生额外的复杂度成本，该成本未反映在上述基本计算中。每查询一天，计算中就会额外增加 1 次调用。

我们来看一个例子：

{
  advertiser {
    # 50 calls
    adSets(first: 50) {
      edges {
        node {
          id
          name

          # 7 calls
          insights(timeRange: {from: "2024-03-01T00:00:00Z", until: "2024-03-08T00:00:00Z"}) {
            timestamps
            reports {
              country
              impressions
              conversions
              spend
            }
          }
        }
      }
    }
  }
}

在此示例中，客户一次最多请求50个ad sets；对于每个ad set，他们请求提供涵盖 3 个指标和1个细分受众群的7天报告数据。

要计算总通话次数，请按以下步骤操作：

50      = 50 ad sets
+
50 x 7  = 350 insights
        = 400 calls

Reporting API最佳实践
1. API 端点
2. 与 API 通信
3. 处理错误
4. 限制