Digital Platform API - API セマンティクス

[アーティクル]
02/23/2024

このページでは、REST API のセマンティクスについて説明します。これには、次の情報が含まれます。

サービスに自身について質問する方法: サポートされているフィールド、フィルター可能なフィールド。
フィルター処理と並べ替えによって必要な情報のみを取得する方法。
さまざまなシナリオでの JSON 応答の "形状"。

このドキュメントでは、 API オンボードプロセスが完了していることを前提としています。

HTTP プロトコル

Digital Platform API では、HTTP プロトコルバージョン 1.1 以降がサポートされています。一部の呼び出しは非推奨の 1.0 バージョンで動作しますが、これは保証されません。クライアントが少なくともバージョン 1.1 を使用して通信していることを確認してください。

API エンドポイント

運用 API エンドポイントの URL はです https://api.appnexus.com。製品 API (HTTP) へのセキュリティで保護されていないアクセスは使用できません。

この API で行われた変更は、運用環境に影響します。承認されたユーザーのみが、この環境の情報または設定を変更する必要があります。

REST セマンティクス

当社の API サービスは RESTful です。 REST (表現状態転送) は、Web ブラウザーから Web サーバーへの通信をモデル化するソフトウェアアーキテクチャの一種です。 API サービスで使用される中心的な REST メソッドとその使用方法を次に示します。

POST	作成する
`GET`	読み取り
`PUT`	更新
`DELETE`	削除

または要求をPOST行う場合は、作成または更新するデータを含む JSON ファイルを含める必要があります。PUT

警告

PUT は、クエリ文字列に追加されない限り 'append=true' 、配列を上書きします。

要求の場合PUT、配列の場合を除き、JSON ファイルに含まれるフィールドのみが更新されます。を使用してPUT配列を更新する場合、要求クエリ文字列"append=true"にを追加しない限り、配列内のすべてのフィールドは、アップロードする新しい配列の内容で上書きされます。

配列を更新するための "レガシ" PUT 要求の例

この例では、"レガシ" メソッドを使用して、クリエイティブ ID 503577の配列を適切に更新するpixelsプロセスについて説明します。つまり、要求のクエリ文字列に文字列"append=true"を追加しない限り、"overwrite arrays on PUT" 動作が発生します。

まず、クリエイティブを見てみましょう。配列には既に 1 ピクセルが含まれていることに pixels 注意してください。

$ curl -b cookies 'https://api.appnexus.com/creative?id=503577'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "503577",
        "start_element": 0,
        "num_elements": 100,
        "creative": {
            "name": null,
            "brand_id": 1,
            "media_url": "https://creative.com/300x250",
            "id": 503577,
            ...
            "pixels": [
                {
                    "id": 196,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url": "https://50.16.221.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}"
                }
            ],
            ...
        }
    }
}

次に、クリエイティブに新しいピクセルを追加するための JSON ファイルを作成します。ファイルには、追加する新しいピクセルと、クリエイティブに既にアタッチされているピクセルの両方が含まれます。

JSON ファイルに既存のピクセルを含めない場合、更新によってクリエイティブからそのピクセルが削除されます。

$ cat creative_update
{
    "creative": {
        "pixels": [
            {
                "format": "url-js",
                "url":"https://12.19.232.312/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}&ref=${REFERER_URL}"
            },
            {
                "id": 196,
                "format": "url-js",
                "url": "https://50.18.232.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}"
            }
        ]
    }
}

次に、JSON ファイル内のPUT情報を使用してクリエイティブを更新する呼び出しを行います。応答の配列には、 pixels 新しいピクセルと古いピクセルの両方が含まれていることに注意してください。

$ curl -b cookies -X PUT -d @creative_update 'https://api.appnexus.com/creative?id=503577'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "503577",
        "start_element": 0,
        "num_elements": 100,
        "creative": {
            "name": null,
            "brand_id": 1,
            "media_url": "https://creative.com/300x250",
            "id": 503577,
            ...
            "pixels": [
                {
                    "id": 196,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url": "https://50.16.221.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}
                     &ref=${REFERER_URL}&campaign_id=147"
                },
                {
                    "id": 197,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url":"https://12.13.234.312/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}&ref=${REFERER_URL}"
                }
            ],
            ...
        }
    }
}

cURLの使用

このドキュメントでは、 curl を使用して HTTP 要求を行います。 Curl は、FTP、FTPS、HTTP、HTTPS、SCP、SFTP、TFTP、TELNET、DICT、LDAP、LDAPS などをサポートする URL 構文を使用してファイルを転送するためのコマンドラインツールです。 Xandr API サービスを実行するために必要なコマンドの構造を示すために、各 API Wiki ページにスクリプトの curl 例が用意されています。さらに、一般的 POST な要求を行う方法の例を次に示します。この例では、認証サービスを使用します。

$ curl -b cookies -c cookies -X POST -d @auth.json 'https://api.appnexus.com/auth'

要求のチャンク	意味
`-c cookies`	というテキスト `"cookies"` ファイルを作成し、セッショントークンを格納します ( 認証サービスによって割り当てられます)。これは、最初の認証の後のに `curl` 必須の引数ではありませんが、含まれている場合、後続の呼び出しには影響しません。
`-b cookies`	テキストファイルに以前に格納した認証トークンを `"cookies"` 取得します。
`-X`	特定の種類の要求 (この場合 `"POST"`は ) を行う予定であることを示します。
`-d`	ファイル (この場合 `"auth.json"`は ) をアップロードすることを示します。
`'https://api.appnexus.com/auth'`	要求を行うサービスの URL。 URL に特殊文字がある場合は、引用符を使用します。

ヒント

要求 URL の一重引用符を使用する

一部の要求では、上記 curl の要求と同様に、要求 URL を一重引用符で囲む必要があります。 UNIX シェルからエラーメッセージが表示される場合は、さらにトラブルシューティングを行う前に、要求 URL に単一引用符が付いていることを確認してください。 UNIX シェルの引用符とエスケープのしくみの詳細については、シェルでの引用符とエスケープに関するこちらのドキュメントを参照してください。

フィルター処理と並べ替え

ほとんどの API サービスでは、フィルター処理と並べ替えがサポートされています。フィルター処理を使用すると、返されるオブジェクトのサブセットを指定できます。並べ替えでは、返されるオブジェクトの順序を制御できます。

ヒント

メンバー全体でオブジェクトを検索する方法については、 Search Service と Lookup Service も参照してください。

注:

フィールドでフィルター処理する場合、フィルター処理に使用するフィールドがフィールドクエリ文字列パラメーターに渡される場合にのみ、フィルター "may" が適用されます。

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

ID のコンマ区切りのリストを渡すことで、ID によって複数の特定のオブジェクトを取得できます。 result オブジェクトには、それらの特定のオブジェクトだけを保持する配列が含まれます。次の例では、ID 1、2、3 のキャンペーンのみをキャンペーンサービスに依頼します。

$ curl -bc -cc 'https://api.appnexus.com/campaign?id=1,2,3
{ 
  "response" : {
     "count" : 3,
     "status" : "OK",
     "campaigns" : [ ... ]
  }
}

ID でフィルター処理する

フィールドのクエリ文字列パラメーターを、ID のコンマ区切りリストで渡します。

例

特定の広告申込情報のすべてのキャンペーンをリクエストする

$ curl -b cookies 'https://api.appnexus.com/campaign?advertiser_id=40&line_item_id=1,2,3'

特定の広告主を要求する

$ curl -b cookies 'https://api.appnexus.com/advertiser?id=3'

ヒント

要求ごとに返されるオブジェクトは 100 個のみです

改ページに関係なく、返すことができるオブジェクトの最大数は 100 です。 100 個を超えるオブジェクトを要求した場合、最初の 100 個のみが返され、エラーメッセージは表示されません。 API の結果を改ページ処理する方法の詳細については、「ページング」を参照してください。

最小値と最大値でフィルター処理する

、または money 型intdatedoubleのフィールドは、と maxでminフィルター処理できます。例:

$ curl -b cookies 'https://api.appnexus.com/campaign?min_id=47'
$ curl -b cookies 'https://api.appnexus.com/campaign?min_advertiser_id=20'

型dateのフィールドは、と nmax でnminフィルター処理することもできます。 nminフィルターを使用すると、指定した日付の前後nullの日付を検索できますnmax。また、フィルターを使用すると、指定した日付よりnull前の日付を検索できます。例:

$ curl -b cookies 'https://api.appnexus.com/campaign?nmax_start_date=2012-12-20+00:00:00'
$ curl -b cookies 'https://api.appnexus.com/campaign?nmin_end_date=2013-01-01+00:00:00'

前の例の必須の日付/時刻構文に注意してください。YYYY-MM-DD+HH:MM:SS

日付でフィルター処理するもう 1 つのオプションは、フィルターを使用することです min_last_modified 。

$ curl -b cookies 'https://api.appnexus.com/campaign?min_last_modified=2017-10-27+21:00:00'

フィールド名でフィルター処理する

応答をオブジェクトの特定のフィールドに制限するには、フィールド名の fields コンマ区切りのリストを使用してクエリ文字列パラメーターを渡します。例:

$ curl -b cookies "https://api.appnexus.com/user?current&fields=username,user_type,id"
{
    "response":{
        "status":"OK",
        "count":1,
        "start_element":0,
        "num_elements":100,
        "user":{
            "id":14311,
             "username":"rloveland",
             "user_type":"admin"
        }
    }
}

フィールドのその他のフィルター

API 応答に関する次のフィールドベースのフィルターがサポートされています。

not_*
like_*
min_*
max_*
nmin_*
nmax_*
having_*
having_min_*
having_max_*

例

$ curl -b cookies 'https://api.appnexus.com/placement?like_[fieldName]=partialValue'

検索

一部のサービスでは、ID または名前を検索するためのクエリ文字列パラメーターとしてサポート search されています。例:

$ curl -b cookies 'https://api.appnexus.com/placement?search=17'

並べ替え

並べ替えるには、クエリ文字列パラメーターをsort使用し、並べ替えるフィールドの一覧と、昇順 () と降順 (ascdesc) のどちらを使用するかを渡します。例:

$ curl -b cookies 'https://api.appnexus.com/campaign?advertiser_id=1&sort=id.desc'

Paging

ページを作成するには、パラメーターとパラメーターをstart_elementnum_elements使用します。が指定されていない場合 num_elements 、既定値は 100 です (最大値でもあります)。

$ curl -b cookies 'https://api.appnexus.com/campaign?start_element=20&num_elements=10'

に追加する `PUT`

呼び出しのクエリ文字列にをPUT含append=trueめることで、ユーザーはすべての子オブジェクトを置き換える代わりに、特定の子オブジェクトのみを更新できます。つまり、呼び出しで配列全体を新しい配列で PUT 上書きするのではなく、クエリ文字列でを使用 append=true して、1 つの要素を長い配列に追加できます。

この例では、呼び出しで PUT を使用append=trueして、Plugin Service の配列内のmember_availabilitiesオブジェクトのフラグを切り替えますis_available。クエリ文字列に append=true フラグがない場合、新しい項目は配列全体を置き換えます。この例では、追加されるだけです。

最初に、変更するオブジェクトを見てみましょう (これらの例では、jq を使用して JSON をスライスしてダイスします)。どちらの可用性もに true設定されます。

次の JSON を送信して、いずれかのオブジェクトでフラグをis_availablemember_availabilityオフにします。

$ cat plugin-update.json
{
    "plugin" : {
        "developer" : {
            "id" : 1
        },
         "member_availabilities" : [
            {
                "is_available" : false,
                 "id" : 4
            }
        ],
         "name" : "ccc"
    }
}

通常、上記の JSON を呼び出しに送信すると、 PUT 配列全体 member_availabilities が上書きされます。ただし、今回は、呼び出しのクエリ文字列にを追加 "append=true" します。これにより、がであるオブジェクト id だけを変更するように API に指示されます 4。出力を調べることで、それが行われることを確認できます。

$ curl -bc -X PUT -d @plugin-update.json 'https://api.appnexus.com/plugin?id=13&append=true' | jq '.response.plugin.member_availabilities'
[
  {
    "is_available": false,
    "id": 4
  },
  {
    "is_available": true,
    "id": 7
  }
]

JSON の基本的な構造

JSON オブジェクトのコンポーネントの構文と、その意味を次に示します。

オブジェクト:

{. . . }

配列:

[. . . ]

文字列:

". . ."

キーを英数字の文字列値に関連付けます。

"key":"string"

キーを数値に関連付けます。

"key":int

それらをまとめる例:

{
    "campaign": {
        "name": "my campaign",
        "id": 1434,
        "creatives": [
                {
                    "id": 4162,
                    "state": "active"
                }
            ],
}
}

JSON フィールド型

POST 要求には PUTJSON データが必要です。要求の場合 PUT 、要求に含まれる JSON フィールドのみが更新されます。その他のフィールドはすべて変更されません。

フィールドが異なると、さまざまな種類の値が必要になります。次の型の表は、 JSON 標準で定義されているものを拡張しています。

型	説明	例
ブール値	true または false。	`true`
string(100)	100 文字以下の文字列。	`"Homepage Pixel"`
int	SyncSchedule パラメーターは、??? を指定します。このパラメーターの有効な値は次のとおりです。	`87`
decimal	ジェネリック 10 進数。	`3.0`
浮動小数点数	32 ビットの有効桁数を持つ浮動小数点数。	`3.14`...
double	64 ビットの有効桁数を持つ浮動小数点数。	`3.14`...
列挙	所定の値の数の 1 つ。	`"male"` または `"female"`
お金	金額を表すために使用される浮動小数点の数値。	`19.23`
timestamp	YYYY-MM-DD HH:MM:SS という形式の日付と時刻の文字列。特に記載がない限り、すべてのタイムゾーンは UTC です。	`"2009-01-14 05:41:04"`
date	上記のタイムスタンプを参照してください。
object	現在のフィールドの下にあるサブフィールドのラッパー。次の例では、フィールド `"brand"` はマルチオブジェクトです。	以下のオブジェクト型の例を参照してください。
配列	1 つ以上の値を含むリスト。この API では、ほとんどの場合、配列にはオブジェクト、整数、または文字列のリストが含まれています。	以下の配列型の例を参照してください

オブジェクト型の例

"brand": {
"id": 466,
"name": "PKR"
}

配列型の例

"members" : [
{
"id": 1234,
"member_use_deal_floor": true,
"member_ask_price": 2.15,
"name": "Buyer 1"
},
{
"id": 5561,
"member_use_deal_floor": true,
"member_ask_price": 2.25,
"name": "Buyer 2"
}
]

レポート API が異なる方法と理由

Report Service を介して使用できるレポート API は、他の API とは異なる方法で動作します。独自のマルチステップ要求と応答フローがあります。これは、大量のデータを処理するため必要です。この処理は非同期的に実行する必要があります。

レポートを取得する方法については、レポートサービスに関するページを参照してください。

レポート API を効果的に使用する方法について説明するチュートリアルについては、「 Report Pagination」を参照してください。

アンダースコアとハイフンに関するメモ

JSON フィールドと値には、アンダースコア (例: audit_type_direct) が使用されます。

URL 内の API サービス名は、ハイフネーションされます (例: https://api.``appnexus``.com/insertion-order)。

応答コード

すべての API サービスは JSON データを返します。サービス呼び出しが成功すると、JSON 応答にに"OK"設定されたフィールドが"status"含まれます。および呼び出しPUTへのPOST応答には、関連オブジェクトの ID と、そのオブジェクトの関連属性も含まれます。すべての応答には、 "dbg_info" API 呼び出しと応答に関する情報を伝達するオブジェクトが含まれます。これは Xandr 内部でのみ使用され、サポートの問い合わせ中に要求される可能性があります。

エラーメッセージ

無効な入力が API に送信されると (正しくないパスワードなど)、およびフィールドを含む "error""error_id" JSON 応答が返されます。

$ cat auth
{
  "auth": {
     "username":"user1",
     "password":"Wr0ngP@ss"
  }
}
$ curl -b cookies -c cookies -X POST -d @auth 'https://api.appnexus.com/auth'
{
    "response": {
        "error_id": "NOAUTH"
        "error": "No match found for user\/pass",
        "dbg_info": {
            ...
        }
    }
}

この "error" フィールドは、エラーの詳細な説明が含まれているので、デバッグ目的で役立ちます。フィールドは "error_id" 、次の表に示すようにプログラムで使用できます。

Error_ID	意味	応答する方法
`INTEGRITY`	クライアント要求に一貫性がありません。たとえば、要求は、アクティブな配置にアタッチされている既定のクリエイティブを削除しようとします。	要求ロジックの整合性を確認します。
`LIMIT`	ユーザーは、特定の型の許可されるオブジェクトの最大数に達しました。	制限の下に取得する不要なオブジェクトを削除します。オブジェクトを削除できない場合は、Xandr の担当者にお問い合わせください。
`NOAUTH`	ユーザーがログインしていないか、ログイン資格情報が無効です。	認証サービスを使用してトークンを取得するか、要求でユーザー名とパスワードをチェックします。
`NOAUTH_DISABLED`	ユーザーのアカウントが非アクティブ化されました。	別のユーザーでログインするか、API アクセス専用のユーザーアカウントを作成します。
`NOAUTH_EXPIRED`	ユーザーのパスワードの有効期限が切れているので、リセットする必要があります。	認証サービスを使用して新しいトークンを取得します。
`SYNTAX`	要求の構文が正しくありません。	メッセージを `"error"` 使用して問題を特定し、コードを修正します。
`SYSTEM`	システムエラーが発生しました。	Xandr の担当者にお問い合わせください。
`UNAUTH`	ユーザーは、要求されたアクションを実行する権限がありません。	メッセージを `"error"` 確認し、コード内のロジックが正しいことを確認します。

次の方法で共有

Digital Platform API - API セマンティクス

HTTP プロトコル

API エンドポイント

REST セマンティクス

cURLの使用

フィルター処理と並べ替え

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

ID でフィルター処理する

例

特定の広告申込情報のすべてのキャンペーンをリクエストする

特定の広告主を要求する

最小値と最大値でフィルター処理する

フィールド名でフィルター処理する

フィールドのその他のフィルター

例

検索

並べ替え

Paging

に追加する `PUT`

JSON の基本的な構造

JSON フィールド型

オブジェクト型の例

配列型の例

レポート API が異なる方法と理由

アンダースコアとハイフンに関するメモ

応答コード

エラーメッセージ

その他のリソース

次の方法で共有

Digital Platform API - API セマンティクス

HTTP プロトコル

API エンドポイント

REST セマンティクス

cURLの使用

フィルター処理と並べ替え

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

ID でフィルター処理する

例

特定の広告申込情報のすべてのキャンペーンをリクエストする

特定の広告主を要求する

最小値と最大値でフィルター処理する

フィールド名でフィルター処理する

フィールドのその他のフィルター

例

検索

並べ替え

Paging

に追加する PUT

JSON の基本的な構造

JSON フィールド型

オブジェクト型の例

配列型の例

レポート API が異なる方法と理由

アンダースコアとハイフンに関するメモ

応答コード

エラー メッセージ

関連項目

その他のリソース

に追加する `PUT`

エラーメッセージ