Bidders - API セマンティクス

このページでは、インプレッション バス REST API を使用する方法について説明します。 これには、次の情報が含まれます。

• 認証方法
• サービスに自身について質問する方法 - サポートされているフィールド、フィルターに使用できるフィールド
• 応答コードとエラー

HTTP プロトコル

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

API エンドポイント

REST

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

このドキュメントでは、REST 要求を行うためにcURLを使用します。 cURLは、FTP、FTPS、HTTP、HTTPS、SCP、SFTP、TFTP、TELNET、DICT、LDAP、LDAPS、FILE をサポートする URL 構文でファイルを転送するためのコマンド ライン ツールです。 各 API Wiki ページのサンプル スクリプトは、Xandr の cURL API Services を実行するために必要なコマンドの構造を明確にします。

PUT に追加する

要求の場合PUT、配列の場合を除き、JSON ファイルに含まれるフィールドのみが更新されます。

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

メタ呼び出し

すべての Bidder Services ではメタ呼び出しがサポートされています。この呼び出しでは、サービスのフィールドと値の種類が返されます。 メタ呼び出しは次のようになります。

$ curl -b cookies -c cookies 'https://api.adnxs.com/SERVICE/meta'

たとえば (メタ呼び出しの部分的な出力):

            "bidder_id": {
                "type": "int"
            },
            "agent_id": {
                "type": "int"
            },
            "code": {
                "type": "string"
            },
            "active": {
                "type": "boolean"
            }

要求レコードの GET 制限

API への GET 要求の末尾にこの文字列を追加すると、取得されるレコードの数が制限されます。

?start_element=N&num_elements=N

例

segment/1?start_element=0&num_elements=1000
member?start_element=0&num_elements=100
creative/1?start_element=0&num_elements=200

• 最初の要素は要素 0 です。
• すべての GET 応答には、その GET 要求に一致する要素の合計数を示す "count" プロパティがあります。
• これは、GET 以外の方法で要求されるクリエイティブ検索サービスなどのレポート以外のサービスにも適用されます。

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

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

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

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

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

ID でフィルター処理する

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

例: 特定のメンバーのすべてのクリエイティブを要求する

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?member_id=123,987' 

フィルター処理とMinMax値

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

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_id=47'
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_brand_id=20'

型 date のフィールドは、フィルターを使用して min_last_modified フィルター処理できます。 必須の日付/時刻構文に注意してください: YYYY-MM-DD+HH:MM:SS

$ curl -b cookies 'https://api.adnxs.com/creative/114?min_last_activity=2017-10-27+21:00:00'

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

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

$ curl -b cookies "https://api.adnxs.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 -c cookies 'https://api.adnxs.com/creative?like_[fieldName]=partialValue'

JSON フィールドの値

POST 要求 PUT には JSON 形式のデータが必要です。 POST request は通常、データベースにオブジェクトを作成するため、そのオブジェクトに関するすべての情報が必要です (後で PUT 要求によって変更されない限り)。 要求の場合 PUT 、要求に含まれる JSON フィールドのみが更新されます。 その他のフィールドはすべて変更されません。

フィールドが異なると、さまざまな種類の値が必要になります。

認証

API を使用する前に、ユーザー名とパスワードで自分を認証する必要があります。 詳細については、 認証サービス に関するページを参照してください。

応答コード

すべての API Services は、JSON 形式のデータを返します。 サービス呼び出しが成功すると、JSON 応答に に"OK"設定されたフィールドが"status"含まれます。 POST 呼び出しと PUT 呼び出しへの応答には、入札者、メンバー、タグ、クリエイティブなどの関連オブジェクトの ID と、そのオブジェクトの関連属性も含まれます。 (次の例では、Cookie を使用して認証トークンを格納し、ファイル "tag" を Tiny Tag Service に追加しています)。

$ curl -b cookies -c cookies -X POST --data-binary @tag https://api.adnxs.com/tt/32/
{
    "response": {
        "status": "OK",
        "id": "242"
    }
}

エラー

無効な入力が API に送信されると (たとえば、パスワードが正しくありません)、JSON 応答と フィールドが返"error""error_id"されます。 一部のエラー条件については、省略可能 "error_description" なフィールドと "error_code" フィールドも表示される場合があります。

$ curl -b cookies -c cookies 'https://api.adnxs.com/api/auth?username=admin&password=Wr0ngP@ss'
{
    "response": {
        "error": "No match found for user\/pass",
        "error_id": "NOAUTH"
    }
}

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

関連トピック

Bidder API Services