Digital Platform API - API のベスト プラクティス

生データの取得、広告配信パズルの独自の部分へのフック、またはインフラストラクチャの上に構築することで、当社のプラットフォームを利用することに興奮しています。 可能な限り最高のエクスペリエンスを提供し、API の進化に合わせてアプリケーションを正常に保ついくつかの基本ルールがあります。 構築を開始するときに、実装コンサルタントと連絡を取り合ってください。

API Dos

必要なオブジェクトのみを取得します。

ID で複数のオブジェクトを取得する

ほとんどのサービスでは、ID による複数の特定のオブジェクトの取得がサポートされています。 これを行うには、クエリ文字列に ID のコンマ区切りのリストを追加します。 たとえば、次の要求では、指定した ID を持つ発行元のみが返されます。

$ curl -b cookies -c cookies 'https://api.appnexus.com/publisher?id=2,3,5,8,13,21'

結果をフィルター処理する

フィルター処理を使用すると、返されるオブジェクトのサブセットを指定できます。 たとえば、次の呼び出しでは、 "active" 状態の行項目のみが返されます。

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?state=active'

int、double、date、money 型のフィールドの場合は、フィルターに min_ または max_ を追加できます。 たとえば、次の要求では、2013 年 1 月 1 日以降に変更された行項目のみが返されます。

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?min_last_modified=2019-01-01+00:00:00'

API 呼び出しで "タイムアウトまたはメモリの問題が原因で要求が失敗しました" というエラーが返される場合は、クエリ パラメーター に add_mappings=false を追加 できます。 このパラメーターを追加すると、最上位レベルの API オブジェクトのみが返されますが、入れ子になった子は返されません。

例えば、

$ curl -b cookies -c cookies "https://api.appnexus.com/publisher?id=2,3,5,8,13,21&add_mappings=false"

結果のページ分割

改ページのサポートを利用するには、アプリケーションを記述する必要があります。 GET要求のクエリ文字列にstart_elementとnum_elementsを指定することで、結果を改ページ処理できます。 たとえば、次の要求は、応答の最初の 50 個のオブジェクトを返します。

$ curl -b cookies -c cookies 'https://api.appnexus.com/creative?start_element=0&num_elements=50'

次の 50 を取得するには、 start_element=50を設定するだけです。

通話を調整する

1 分あたりの API に対して行うことができる要求の数には制限があります。 調整の制限を超えた場合、API は HTTP 429 (要求が多すぎます) 応答コードと、応答内容のエラー メッセージで応答します。 また、より多くの API 呼び出しを試行するまでに待機する秒数を指定する Retry-After フィールドを持つ応答ヘッダーも返します。

curl を使用して API 呼び出しを行う場合は、要求に -v パラメーターを含めることで応答ヘッダーを取得できます。

curl -b cookies -v 'https://api.appnexus.com/advertiser
 
> GET /advertiser HTTP/1.1
> Host: api-test.appnexus.com
> User-Agent: curl/7.43.0
> Accept: */*
...
< Retry-After: 31
< X-Route: /advertiser
< X-Route-Time: 86
...

この場合は、31 秒 ( Retry-After フィールドの値) で要求を再試行できます。

スクリプトから API を呼び出す場合は、API 呼び出しを行うときに 429 応答コードを確認する必要があります。 このコードを受け取った場合は、応答ヘッダーの Retry-After フィールドから返された時間スリープします。 指定した時間スリープ状態にした後、スクリプトを続行できます。

同時要求の上限は一度に 15 個です。 この制限を超える場合、 http コード 200 が返されますが、 エラー ペイロードが返されます。

レート制限の詳細については、「 API 使用状況の制約」 を参照してください。

で配列を更新する "append=true"

API を使用して配列値を更新すると、オブジェクトの配列値は、 PUT 要求で指定された値で上書きされます。 これは、配列の値を消去し、更新されたデータに置き換えることを意図した動作である場合に問題ありません。 ただし、フラグを使用して、データを置き換えるのではなく、配列に追加できます。 これは、非常に長い配列を更新する場合に特に便利です。 クエリ パラメーター append=true を PUT 要求に追加して、更新プログラムを追加モードに設定できます。

この例では、次の country_targets 配列を持つ単純な Profile オブジェクトがあるとします。

更新前のプロファイル オブジェクト

// Before Append
{
        "profile": {
                "code": "Test Profile",
                "country_targets": [
                {
                  "country": "US",
                  "name": "United States"
            }
          ]
        }
}

PUT呼び出しでappend=trueを使用してこのオブジェクトを更新する場合は、プロファイルの既存のcountry_targets データを上書きすることを恐れずに、次の JSON データを使用できます。

JSON 更新データ

// Update Object
{
    "profile": {
        "country_targets": [
                        {
                                "country": "GR",
                                "name": "Greece"
                }
        ]
    }
}

次の CURL コマンドを使用します ( <profile_ID> を適切な値に置き換えます)。

CURL の例

$ curl -b cookie -c cookie -X PUT -s -d '@json/profile.json' "https://api.appnexus.com/profile?id=<profile_ID>&append=true"

その結果。 プロファイル オブジェクトは、次のように更新されます。

結果として得られるプロファイル オブジェクト

// After Append
{
        "profile": {
                "code": "Test Profile",
                "country_targets": [
                {
                        "country": "US",
                        "name": "United States"
            },
                        {
                                "country": "GR",
                                "name": "Greece"
                }
        ]
        }
}

構成駆動型 API エンドポイントを使用する

API ベース URL を簡単に変更できることを確認します。 次の例では、API URL は変数として定義されており、コード ベース全体で使用できます。 その URL を変更する必要がある場合は、1 つの場所で変更できます。

$config = "https://api.appnexus.com";

API ラッパーを構築する

要求を送信し、応答を処理するコードを一元化することをお勧めします。 これにより、ログ記録、エラー処理などを 1 つの場所で実行できます。

レポートの無駄を取り除き、集中したままにする

レポートが不必要に大きくなるのを防いだり、処理に時間がかかるのを防ぐためのヒントを次に示します。

• report_intervalを短くする (つまり、有効期間からlast_48_hours)
• より高いレベルのフィルターを追加する (たとえば、特定のパブリッシャー、広告主、広告申込情報など)
• これにより行数が指数関数的に増加するため、きめ細かい買い側と販売側のディメンション (クリエイティブと配置) を組み合わせることは避けてください。 このような組み合わせについて報告する必要がある場合は、 一括レポート フィード または ログ レベルのデータ フィードの使用を検討してください。

非常に大きなレポートをプルする必要がある場合は、「 レポートの改ページ」の手順を使用します。

応答の追加フィールドを許可する

API チームが新しい機能を実装する場合は、さまざまな API サービスに新しいフィールドを含める必要があります。 統合は、以前に返されなかった各サービスの追加フィールドを処理するのに十分な柔軟性を備えている必要があります。

破壊的変更に注意する

新しい機能を追加すると、サービスは絶えず変化しますが、クライアントが API を基に構築するアプリケーションも適切に適応できるように、安定性を生み出すために最善を尽くします。

破壊的変更を導入する場合、運用環境の API の 2 つのバージョンをサポートします。1 つは破壊的変更あり、もう 1 つは破壊的変更なしで 60 日間サポートされます。 これらの変更は、API リリース ノートで発表します。 破壊的変更を構成する内容の詳細については、「破壊的変更 」ポリシーを参照してください。

オブジェクトの制限に注意してください

各メンバーがプラットフォーム上で作成および使用できるオブジェクトの数を制限します。 この制限には、非アクティブなオブジェクトと未使用のオブジェクト (非アクティブ状態に設定された広告申込情報、インプレッションを配信したことがない配置など) が含まれます。 オブジェクト制限サービスを使用して制限を表示し、使用状況を事前に監視する必要があります。

プロセスのスケジュール設定に注意してください

可能であれば、プロセスが互いに重複しないようにスケジュールします。 営業時間中に一括操作を実行する必要がない場合は、これらのプロセスをピーク時以外の時間帯にスケジュールして、1 日を通して API の使用状況を最大化してください。 1 分間に一定量の READ 呼び出しと書き込み呼び出しが割り当てられている点に注意してください。 API を呼び出していない時間を利用して、必要なときにヘッドルームを追加し、時間に依存する操作の優先順位を付けます。

API Don'ts

API 呼び出しが成功したと想定しないでください

成功した API 呼び出しはすべて、"OK"の"status"を含む応答を受け取ります。 応答にこの状態が含まれていない場合、何らかの理由で呼び出しが失敗しました。 "status"が"error"されている場合、エラー メッセージが応答に含まれます。 成功した応答の例を次に示します。

{
   "response": {
      "status": "OK",
      "line-item": {
         ...
      }
   }
}

既定のフィールドに依存しない

既定のフィールド値に依存するのではなく、必要なフィールド値を渡すことがベスト プラクティスです。 既定値が変更され、既定値に依存している場合は、予期しない結果が発生する可能性があります。

不要な更新を行わない

オブジェクトを更新するときに、API に変更されているフィールドのみを渡すことで、不要な更新を行わないようにすることができます。 この方法を確実に行うには、 GET 呼び出しをキャッシュし、キャッシュを行う変更と比較し、異なる場合にのみ PUT 呼び出しを行います。

たとえば、サイト上のすべての配置で cost_cpm を更新するなど、セット内のすべてのオブジェクトを更新する必要がある場合は、各オブジェクトを盲目的に PUT 呼び出しを行う必要があります。 代わりに、 GET 呼び出しを発行して、セット内の各オブジェクトの現在の状態を取得します。 可能な場合は、 API Semantics に記載されているフィルター処理と並べ替え機能を使用して、更新が必要なオブジェクトのみを取得してください。 返されたオブジェクトの現在の状態を目的の状態と比較し、実際に更新が必要なオブジェクトに対してのみ PUT を発行します。

不必要に認証しない

認証すると、トークンは 2 時間有効なままになります。 この時間内に再認証する必要はありません。 再認証を行う場合は、 です。 次の制限事項に注意してください。 API を使用すると、5 分間に 10 回正常に認証できます。 この 5 分以内にそれ以降の認証が試行されると、エラーが発生します。

認証手順については、「 認証サービス」を参照してください。

すべてのレポートを同時にプルしない

これにより、レポート バックエンドが過負荷になり、レポートが遅延し、1 日の後半に実行されるレポートにも影響を与える可能性があります。 詳細については、「レポート サービス」ページの「レポート調整」セクションを参照してください。

レポート サービスに一括要求を行わない

アーキテクチャで 1 時間または 1 日あたりのレポート サービスからの複数の要求を呼び出す場合は、より多くのデータを含む上位レベルのレポートを調査して、API への呼び出しが少なくても必要なデータを取得できるかどうかを確認します。

たとえば、ネットワーク内のすべての広告主とパブリッシャーに対して時間単位のレポートを要求する場合は、 Network Analytics レポート を使用してニーズを満たしているかどうかを判断します。 広告主の Analytics レポートまたは Publisher Analytics レポートに対して個別の要求を行う代わりに使用することを検討し、ユース ケースとの一致を向上させます。

使用可能なすべてのレポートとそのフィールドの詳細については、 Reporting Service の API ドキュメントを参照してください。