Reporting API のベストプラクティス

Tapjoy Offerwall Reporting API のエンドポイント、リクエストの構造、エラー処理について理解を深め、正確な収益化データに効果的にアクセスします。

読み終わるまでの所要時間 4 分

最終更新 10日前

Reporting API を使用すると、広告主とパブリッシャーは GraphQL クエリ言語を使用して、Tapjoy プラットフォームのレポートデータにアクセスし、Offerwall コンテンツを管理できます。GraphQL の詳細については、GraphQL の公式ウェブサイトを参照してください。 API エクスプローラーは、クエリの作成を支援します。左上隅にある本のアイコンをクリックすると、ドキュメントエクスプローラーが展開され、クエリで使用できるフィールドと指標に関する情報が表示されます。

本アイコンをクリックすると表示される Reporting API エクスプローラーのドキュメントエクスプローラーパネル

API エンドポイント

Reporting API には 1 つのエンドポイントがあります。


https://api.tapjoy.com/graphql

エンドポイントは、実行される操作に関係なく、同じままです。

API との通信

アクセストークンを取得したら、API にリクエストできます。クエリとミューテーションのどちらを実行する場合でも、JSON エンコードされた本文が HTTP POST を介して提供され、API のリクエストを形成できます。リクエストの例:


  POST /graphql Host: api.tapjoy.com Authorization: Bearer <OAuth Token>{  "query": "query { user { firstName } }"}

エラーへの対処

API の使用時に発生する可能性のあるエラーには、以下のいくつかのカテゴリがあります。

サーバー/ネットワークエラー
認証/承認エラー
クエリ構文エラー
データ検証エラー

システムを適切に統合するには、システムがこれらのカテゴリのエラーをどのように処理すべきかを検討する必要があります。

注

Reporting API はアトミックです。つまり、1 つのクエリで複数のアクションを実行する場合、構成ステップのいずれかが失敗するとクエリ全体が失敗します。

以下で説明する各カテゴリは、コンテキストに以下のクエリを使用します。


  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 ドキュメントを参照し、対話型エクスプローラーでクエリをテストすることです。

データ検証エラー

すべての必須フィールドが入力され、適切に構築されたミューテーションを提供しても、ビジネスの検証によって失敗する可能性があります。例えば、以下のように広告主が 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 状態コード

このシナリオに対処する最善の方法は、(パス経由で) エラーメッセージを対応するフィールドとともにユーザーに表示することです。

制限事項

Reporting API には、過剰な API 呼び出しや濫用的な API 呼び出しを防止するための一定の保護が備わっています。統合が上限を超えている場合は、Tapjoy のアカウントマネージャーやサポートに連絡して、統合を最適化する方法や上限を増やす方法を確認してください。以下の例は広告主のコンテキストで示されていますが、パブリッシャーの統合にも適用されます。

データリテンション

Reporting API は過去 2 年間のデータにアクセスできます。

ページ処理

ページ処理タイプをクエリする場合、クライアントは以下を行う必要があります。

```
first
```
または
```
last
```
引数を指定する
1 ページ 100 ノード以下にする

最大値を超えた場合、結果は切り捨てられ、その結果、要求された最初と最後の引数は無視されます。例を次に示します。


  {  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      }    }  }}

上記のクエリでは、カーソル位置 "Mg==" から最大 50 個の広告セットが返されます。その位置は、前のクエリから返された endCursor に基づいて決定されます。hasNextPage が false のとき、ページ処理は完了したと見なされます。ページ処理の詳細については、GraphQL のウェブサイトを参照してください。

呼び出しの複雑さ

スキーマ検証に合格するには、すべての Marketing API 呼び出しが 10,000 回を超えてはなりません。この場合の "呼び出し" とは、リソースのリクエストを指します。GraphQL では、複数の呼び出しを 1 つのクエリにまとめることができるため、1 つのクエリの呼び出しの合計数は、クエリが実行される前に API によって事前に計算されます。呼び出しの数は、結果から選択されたリソース (キャンペーン、広告セット、広告、アプリ、分析情報など) の数とほぼ等しくなります。上記の同じ例を考えてみましょう。


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

この例では、クライアントは一度に最大 50 個の広告セットを要求します。各広告セットにつき、クライアントはその広告セットから最大 50 個の広告を要求します。合計呼び出し数は、以下のように計算します。


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

現時点では、1 時間あたりの呼び出し数にレート制限はありません。ただし、これは今後変更される可能性があります。

分析情報の複雑さ

レポートの分析情報に対してクエリを実行すると、どのようなレベルでも、上記の基本計算には反映されない複雑さのコストが追加で発生します。クエリが実行される日ごとに、さらに 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 個の広告セットを要求します。各広告セットにつき、クライアントは 3 つの指標と 1 セグメントにわたる 7 日間分のレポートデータを要求します。合計呼び出し数は、以下のように計算します。


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

ドキュメント

エンジン

サービス

Grow

産業

サポート

Offerwall

収益化の開始

ユーザー獲得の開始

Unity SDK の統合