英語で読む

次の方法で共有


Bidders - API セマンティクス

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

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

注意

特定の API サービスを操作する方法の詳細については、 API Services のリンクを参照してください。

HTTP プロトコル

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

API エンドポイント

環境 URL Notes (メモ)
生産 https://api.adnxs.com データのプライバシーを確保するために、運用 API にセキュリティで保護されたエンドポイント (https://) を使用する必要があります。 製品 API (HTTP) へのセキュリティで保護されていないアクセスは使用できません。

REST

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

REST メソッド 使用方法
POST create/add
GET 読み取り/取得
PUT update/modify
DELETE delete

このドキュメントでは、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

注意

要求に関係なく返すことができる要素の最大数は 100 です。

  • 最初の要素は要素 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' 

注意

改ページに関係なく、要求ごとに返すことができるオブジェクトの最大数は 100 です。 100 個を超えるオブジェクトを要求した場合、最初の 100 個のみが返され、エラー メッセージは表示されません。

フィルター処理とMinMax

、または moneyintdatedoubleのフィールドは、 と maxminフィルター処理できます。 例:

$ 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 フィールドのみが更新されます。 その他のフィールドはすべて変更されません。

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

説明
配列 複数の値を使用できる [87,45]
ブール値 True/False はい
倍精度浮動小数点数 浮動小数点数のビット空間の 2 倍の浮動小数点数。 3.12
列挙 事前割り当て値の配列の 1 つの要素のみ 男性/女性
浮動小数点数 浮動小数点数 3.12
Int 整数 87
String(100) 100 文字以下の文字列 male_26_likes_cheese
Timestamp YYYY-MM-DD HH:MM:SS 形式の日付と時刻の文字列 2009-01-14 05:41:04
符号 なし 正の整数のみ 745

認証

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" 、次のようにプログラムで使用できます。

Error_ID 意味 ロジック
NOAUTH 認証情報が見つからないか無効です /auth を使用して有効なトークンを取得する
UNAUTH ユーザーは要求されたアクションを実行する権限がありません 'error' メッセージを確認し、コード内のロジックが正しいことを確認します
構文 要求の構文が正しくありません 'error' メッセージを使用して問題を特定し、コードを修正します
SYSTEM システム エラーが発生しました Xandr にお問い合わせください
整合性 クライアント要求に一貫性がありません。たとえば、アクティブな TinyTag にアタッチされている既定のクリエイティブを削除しようとすると、 整合性の要求を確認する

Bidder API Services