クイックスタート

GraphQL レポーティング API により広告出稿者やパブリッシャーがTapjoyプラットフォームからレポーティングデータにアクセスできるようになります。 GraphQL レポーティング API による広告出稿者のユースケースをマーケティング API セクションで、パブリッシャーのユースケースをパブリッシャー API の例で参照できます。

1. 認証

マーケティング API やパブッリシャー API にアクセスするためには、まず API キーを使用します。このキーは旧ダッシュボードをご利用の場合は https://dashboard.tapjoy.com/reporting/api から取得できます。

LTV プラットフォームをご利用の場合、"Marketing API Key" を使用します。LTVプラットフォームでアプリを選択し、 "設定" -> "アプリ設定" -> "アプリ情報" -> "API Keys" -> "Marketing API Key" から取得します。

リクエストは OAuth2 の標準的な二層認可フローを使用します。 API キーを利用してアクセストークンを要求し、取得したアクセストークンを利用してその後のリクエストの認証として使用します。

アクセストークンを取得する手順はこちらを参照してください。

2. GraphQL エンドポイント

このAPIのエンドポイントは下記の一つのみです:

https://api.tapjoy.com/graphql

このエンドポイントは実行する内容に関わらず同じです。

3. GraphQL を使用する

アクセストークンを取得すれば、API へのリクエストを行えるようになります。API へのリクエストは、クエリの場合でも更新の場合でも JSON エンコードされた body を HTTP POST で送ります。

リクエスト例:

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 が実行出来ない状況では、HTTP レスポンスコード 500 が返ります。

この状況の最善の対応方法は、指数関数的な間隔を空けたリトライを行う事です。

認証 / 承認エラー

認証 / 承認エラーはいくつかの理由で発生します:

OAuth トークンの有効期限が切れた
OAuth トークンが無効
本システムが使用している認証システムの不具合の影響を受けている

こうした種類の状況の場合、HTTP 200 OK レスポンスで下記のデータを受信します:

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

message - 人間可読なエラーの記述
code - HTTP ステータスコードと対応する GraphQL のステータスコード

この状況の最善の対応方法は、新しくアクセストークンを取得して再度リクエストする事です。

クエリ文法エラー

クエリーと更新(mutation) は文法的に正しいか、データスキーマに合致しているかをまず確認されます。入力されたクエリーがいずれかのスキーマ検証に失敗した場合、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のbidを最小値よりも低く使用したとしましょう::

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に含まれるフィールドをユーザーに提示する事です。

クイックスタート
1. 認証
2. GraphQL エンドポイント
3. GraphQL を使用する
4. エラー対応