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

最終更新日: 2024年12月11日

Reporting APIを使用すると、広告主やパブリッシャーは Tapjoy プラットフォームからレポートデータにアクセスしたり、オファーウォール コンテンツを管理したりすることができます。このAPIは GraphQL クエリ言語を使用します。GraphQLの詳細については、公式 ウェブサイト を参照してください。

API Explorer を利用してクエリの作成にご利用できます。左上の本のアイコンをクリックして「Documentation Explorer」を展開し、使用可能なフィールドや指標を確認できます。

1. API エンドポイント

Reporting APIは単一のエンドポイントを持ちます：

https://api.tapjoy.com/graphql

操作の種類に関わらず、エンドポイントは常に同じです。

2. API との通信

アクセストークンを取得後、APIにリクエストを送信できます。APIへのリクエストは、クエリまたはミューテーションに関わらず、HTTP POST で JSON 形式の本文を送信します。

リクエスト例：

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

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

3. エラー処理

API使用時に発生し得るエラーは以下のカテゴリに分類されます：

1. サーバー / ネットワークエラー
2. 認証 / 認可エラー
3. クエリ構文エラー
4. データ検証エラー

システムへの実装を適切に行うために、各カテゴリのエラーに対応できるようにして下さい。

注意：レポートAPIはアトミック（不可分）です。つまり、1つのクエリ内で複数の操作を実行する場合、その中のどれか1つでも失敗すると、クエリ全体が失敗します。

以下のクエリを例に各エラーの説明を行います:

query {
  user {
    firstName
    lastName
  }
}

サーバー / ネットワークエラー

まれにAPIで回復不能なサーバー / ネットワークエラーが発生することがあります。その場合、適切な HTTP ステータスコードが返されます。例えば、クエリを実行できない問題が発生した場合、ステータスコード 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 ステータスコード

このシナリオを処理する最良の方法は、エラーメッセージを対応するフィールド（path 経由）と一緒にユーザーに表示することです。

4. 制限事項

Reporting API には、過剰または不正な API コールを防ぐための保護があります。実装がTapjoy内部の既定の制限を超えている場合は、Tapjoy の AM またはサポートに連絡し、統合の最適化方法や制限の増加について相談してください。

以下の例は広告主を前提としていますが、パブリッシャー統合にも適用されます。

データ保持

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

ページネーション

ページネーション対象の型をクエリする場合、クライアントは以下を行う必要があります:

• first または last 引数を指定する
• 1ページあたり100ノードを超えないこと

最大値を超えた場合、結果は切り捨てられ、指定した first / last 引数は無視されます。

例:

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

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

上記のクエリでは、最大 50 個の AdSet とそれぞれに最大 50 個の広告が返されます。

コレクションをページングするには、開始位置を制御するために after または before 引数を指定する必要があります。例:

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

      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

このクエリでは、カーソル位置 "Mg==" から始まる最大 50 件の AdSet が返されます。この位置は、前回のクエリで返された endCursor に基づいて決定されます。hasNextPage が false になるとページングは完了と見なされます。

ページネーションの詳細は公式の GraphQL ウェブサイトをご覧ください。

コールの複雑さ

スキーマ検証を通過するために、すべての Marketing API コールは 10,000「コール」を超えてはなりません。ここでの「コール」はリソースのリクエストを指します。GraphQL では複数のコールを単一クエリにまとめることが可能なため、クエリの実行前に API によって総コール数が計算されます。

コール数は、結果から選択されたリソース（例：キャンペーン、AdSet、広告、アプリ、インサイトなど）の数とおおよそ等しくなります。

上記の例を再度見てみましょう：

{
  advertiser {
    adSets(first: 50) {     # <= 50 コール
      edges {
        node {
          id
          name

          ads(first: 50) {  # <= 50 コール
            edges {
              node {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

この例では、クライアントは最大50個の AdSet を要求し、各 AdSet に対して最大50個の広告を要求しています。

合計コール数の計算：

50      = 50 AdSet
+
50 x 50 = 2500 Ad
        = 2550 コール

現時点では、1時間あたりのコール数にレート制限はありませんが、将来的に変更される可能性があります。

インサイトの複雑さ

任意のレベルでインサイトをクエリすると、上記の基本的な計算に反映されない追加の複雑さコストが発生します。クエリ対象の日数ごとに追加で 1 コールが加算されます。

この例を考えてみましょう:

{
  advertiser {
    # 50 コール
    adSets(first: 50) {
      edges {
        node {
          id
          name

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

この例では、クライアントは最大50個の AdSet に対して、3つのメトリクスと1つのセグメントに関する 7 日分のレポートデータを要求しています。

コール数の計算:

50      = 50 AdSet
+
50 x 7  = 350 インサイト
        = 400 コール