Creative Custom Request Template サービス

[アーティクル]
10/31/2024

注:

仲介は、Microsoft 収益化 Ad Server のお客様のみが利用できます。

仲介に関するコンテキストについては、「仲介によるインベントリの販売」を参照してください。

メディエーションパートナー (カスタム要求パートナーとも呼ばれます) は、クリエイティブカスタムリクエストパートナーサービスを通じて識別および定義できます。これらのパートナーは、 UI または仲介ネットワークサービスを使用して、顧客固有のネットワークに割り当てられます。

モバイル広告サーバーの仲介をサポートするために、収益化では仲介型のクリエイティブタイプを使用します。サーバー上の静的コンテンツとして存在する標準のクリエイティブとは異なり、仲介されたクリエイティブは、サーバー側のコンテンツを取得する構成可能なコンテナーです。クリエイティブカスタムリクエストテンプレートサービスは、これらの仲介されたクリエイティブを設定する要求を作成するために使用されます。このサービスは、それぞれ異なるクリエイティブカスタム要求パートナーに対応し、クリエイティブカスタム要求テンプレートタイプサービスによって定義されたテンプレート "type" に関連付けられている一連のカスタムテンプレートを管理することでこれを行います。

このドキュメントでは、この API サービスで使用できるフィールドと、使用例について説明します。以下の「例」セクションを参照してください。

注:

仲介クリエイティブの詳細については、クリエイティブサービスに関するページを参照してください。

REST API

HTTP メソッド	エンドポイント	説明
`GET`	https://api.appnexus.com/creative-custom-request-template?id=123	特定のカスタム要求テンプレートを表示します。
`GET`	- https://api.appnexus.com/creative-custom-request-template?member_id=0 - https://api.appnexus.com/creative-custom-request-template?member_id=MEMBER_ID	メンバーが使用できるすべてのカスタム要求テンプレートを表示します。
`GET`	https://api.appnexus.com/creative-custom-request-template/meta	フィルター処理と並べ替えに使用できるフィールドを表示します。
`POST`	https://api.appnexus.com/creative-custom-request-template	カスタム要求テンプレートを作成します。
`PUT`	https://api.appnexus.com/creative-custom-request-template	カスタム要求テンプレートを更新します。
`DELETE`	https://api.appnexus.com/creative-custom-request-template?id=123	カスタム要求テンプレートを削除します。

JSON フィールド

フィールド	種類	説明
`macros`	オブジェクトの配列	これらは、要求で送信されるマクロ (またはクエリ文字列パラメーター) です。「マクロ」を参照してください。並べ替え: いいえフィルター: いいえ
`id`	int	このテンプレートの ID。必須:`PUT` 並べ替え: はいフィルター: はい
`type_id`	int	Creative Custom Request Template Type Service の ID。デフォルト：`null` 必須:`POST` 並べ替え: はいフィルター: はい
`member_id`	int	メディエーションクリエイティブがこのテンプレートに関連付けられるメンバー ID。詳細については、クリエイティブサービスとメンバーサービスに関するページを参照してください。デフォルト：`0` 並べ替え: はいフィルター: はい
`media_subtype_id`	int	このテンプレートのメディアサブタイプ ID。以下の Media サブタイプオブジェクトから派生します。デフォルト：`null` 並べ替え: はいフィルター: はい
`hostname`	string	要求のために呼び出される仲介パートナーホスト。デフォルト：`null` 必須:`POST` 並べ替え: はいフィルター: はい
`uri`	文字列	要求のために呼び出される仲介パートナーホストエンドポイント。デフォルト：`null` 必須 On:`POST`、`is_client`が`false`されている場合は`PUT`。並べ替え: はいフィルター: はい
`port`	int	要求のために呼び出される仲介パートナーホストポート。デフォルト：`80` 並べ替え: はいフィルター: はい
`is_post`	ブール型	要求が `POST`かどうか。デフォルト：`false` 並べ替え: はいフィルター: はい
`content`	string	要求に含まれるペイロード。例: JSON、XML。デフォルト：`null` 並べ替え: はいフィルター: はい
`timeout_ms`	int	パートナーによって指定されるか、Microsoft 収益化によって適用されるタイムアウト。デフォルト：`0` 並べ替え: はいフィルター: はい
`is_client`	ブール型	要求がクライアント側から発信されるかどうか。例: SDK。デフォルト：`false` 並べ替え: はいフィルター: はい
`media_subtype`	配列	このテンプレートを使用できるクリエイティブの表示スタイル。各メディアサブタイプは、スーパーオーディネートメディアの種類に属します。たとえば、"Standard Banner" メディアサブタイプは "バナー" メディアの種類に属します。詳細については、以下の「メディアサブタイプ」を参照してください。並べ替え: いいえフィルター: いいえ
`last_modified`	date	このオブジェクトが最後に更新された日時。並べ替え: はいフィルター: はい
`integration_type`	string	仲介パートナーとの統合の種類。例: SDK、サーバー側、Sync-web-client。
`creative_custom_request_partner_id`	int	仲介パートナーの ID。詳細については、「 Creative Custom Request Partner Service」を参照してください。
`active`	ブール値	テンプレートを使用できるかどうか。
`supply_types`	配列	仲介パートナーから利用可能な需要の種類 (`web`、 `mobile_web`、 `mobile_app`)。
`passback`	object	リクエストに対して受け入れ可能な入札を受け取っていない場合は、この `passback` を広告タグに追加して、次のシステムの入札を許可できます。このオプションを使用するには、ここに記載されているネットワークのパスバックを広告タグに追加します。

マクロ

フィールド	種類	説明
`id`	int	このマクロの ID。デフォルト：`null` 並べ替え: はいフィルター: はい
`template_id`	int	このマクロが関連付けられているクリエイティブカスタム要求テンプレート。デフォルト：`null` 並べ替え: はいフィルター: はい
`code`	string	url に組み込まれるクエリ文字列パラメーター (例: `send_referer`)。並べ替え: はいフィルター: はい
`name`	string	マクロの動作の説明。たとえば、"参照元を送信する必要がある場合はトグル" などです。並べ替え: はいフィルター: はい
`type`	string	パラメーターが受け入れる値の型。手記：`"string"`の既定値も最も一般的です。許可される値は次のとおりです。 - `true_false` - `string` - `url` - `integer` - `decimal` - `string_list` - `select_from_list` デフォルト：`string` 並べ替え: はいフィルター: はい
`is_required`	ブール型	外部広告サーバーの呼び出しでこのマクロが必要かどうか。デフォルト：`true` 並べ替え: はいフィルター: はい
`last_modified`	date	このマクロオブジェクトが最後に更新された日時。並べ替え: はいフィルター: はい

メディアサブタイプ

使用可能なすべてのオプションは、 Media サブタイプサービスとメディアタイプサービスで表示できます。

フィールド	種類	説明
`id`	int	メディアサブタイプの ID。
`name`	string	読み取り専用です。メディアサブタイプの名前。
`media_type_name`	string	読み取り専用です。サブタイプが属するメディアタイプの名前。
`mediatype_id`	int	読み取り専用です。サブタイプが属するメディアタイプの ID。

例

すべてのクリエイティブリクエストテンプレートを表示する

次の例では、標準の Microsoft 収益化マクロを uri フィールドに表示する方法 (例: * $\{USER_IP\} ) と、このサービスによって広告サーバーごとに定義されたカスタムマクロの表示方法の違いに注意してください。 * \#\{MK_SITEID\}。各マクロの定義は、以下のオブジェクトのマクロ配列にあります。


{code}
$ curl -b cookies https://api.appnexus.com/creative-custom-request-template?member_id=0
{
    "response": {
        "status": "OK",
        "count": 4,
        "start_element": 0,
        "num_elements": 100,
        "creative-custom-request-templates": [
            {
                "id": 1,
                "type_id": 2,
                "member_id": 0,
                "media_subtype_id": 1,
                "hostname": "w.inmobi.com",
                "uri": "/showad.asm?mk-siteid=#{MK_SITEID}&mk-carrier=${USER_IP}&h-user-agent=${USER_AGENT_ENC}&h-referer=${REFERER_URL_ENC}&u-id-map=${INMOBI_UID_MAP}&u-latlong-accu=${INMOBI_LAT_LONG_ACCU}&u-age=${AGE}&u-gender=${GENDER}&d-localization=${USER_LOCALE}&d-nettype=${INMOBI_NETTYPE}&d-orientation=${INMOBI_ORIENTATION}",
                "port": 80,
                "is_post": false,
                "content": "",
                "timeout_ms": 200,
                "is_client": false,
                "last_modified": "2013-07-10 19:27:41",
                "media_subtype": {
                    "id": 1,
                    "name": "Standard Banner",
                    "media_type_name": "Banner",
                    "mediatype_id": 1
                },
                "macros": [
                    {
                        "id": 1,
                        "template_id": 1,
                        "code": "MK_SITEID",
                        "name": "MK_SITEID",
                        "type": "string",
                        "is_required": true,
                        "last_modified": "2013-07-10 19:27:41"
                    }
                ]
            },
            {
                "id": 2,
                "type_id": 3,
                "member_id": 0,
                "media_subtype_id": 1,
                "hostname": "ads.mydas.mobi",
                "uri": "/getAd?apid=#{APID}&auid=${DEVICE_MD5}&ua=${USER_AGENT_ENC}&uip=${USER_IP}&age=${AGE}&gender=${GENDER}&zip=${POSTAL_CODE}&lat=${GEO_LAT}&long=${GEO_LON}",
                "port": 80,
                "is_post": false,
                "content": "",
                "timeout_ms": 200,
                "is_client": false,
                "last_modified": "2013-07-10 19:27:50",
                "macros": [
                    {
                        "id": 2,
                        "template_id": 2,
                        "code": "APID",
                        "name": "APID",
                        "type": "string",
                        "is_required": true,
                        "last_modified": "2013-07-10 19:27:50"
                    }
                ]
            },
            {
                "id": 3,
                "type_id": 4,
                "member_id": 0,
                "media_subtype_id": 5,
                "hostname": "ads.mojiva.com",
                "uri": "/ad?zone=#{ZONE}&ip=${USER_IP}&ua=${USER_AGENT_ENC}&url=${REFERER_URL_ENC}&udid=${DEVICE_MD5}&lat=${GEO_LAT}&long=${GEO_LON}&country=${USER_COUNTRY}&region=${USER_STATE}&city=${USER_CITY}&dma=${USER_DMA}&zip=${POSTAL_CODE}",
                "port": 80,
                "is_post": false,
                "content": "",
                "timeout_ms": 200,
                "is_client": false,
                "media_subtype": {
                    "id": 1,
                    "name": "Standard Banner",
                    "media_type_name": "Banner",
                    "media_type_id": 1
                },
                "last_modified": "2013-07-10 19:28:00",
                "macros": [
                    {
                        "id": 3,
                        "template_id": 3,
                        "code": "ZONE",
                        "name": "ZONE",
                        "type": "string",
                        "is_required": true,
                        "last_modified": "2013-07-10 19:28:00"
                    }
                ]
            },
            {
                "id": 4,
                "type_id": 5,
                "member_id": 0,
                "media_subtype_id": 5,
                "hostname": "a.jumptap.com",
                "uri": "/a/ads?hid_sha1=${DEVICE_SHA1}&idfa=${DEVICE_APPLE_IDA}&pub=#{PUB}&site=#{SITE}&spot=#{SPOT}&url=${REFERER_URL_ENC}&ua=${USER_AGENT_ENC}&client-ip=${USER_IP}&country=${USER_COUNTRY}&ll=${JUMPTAP_LAT_LONG_ENC}&mt-age=${AGE}&mt-gender=${GENDER}",
                "port": 80,
                "is_post": false,
                "content": "",
                "timeout_ms": 200,
                "is_client": false,
                "media_subtype": {
                    "id": 5,
                    "name": "Interstitial",
                    "media_type_name": "Interstitial",
                    "media_type_id": 3
                },
                "last_modified": "2013-07-10 19:28:10",
                "macros": [
                    {
                        "id": 4,
                        "template_id": 4,
                        "code": "PUB",
                        "name": "PUB",
                        "type": "string",
                        "is_required": true,
                        "last_modified": "2013-07-10 19:28:10"
                    },
                    {
                        "id": 5,
                        "template_id": 4,
                        "code": "SITE",
                        "name": "SITE",
                        "type": "string",
                        "is_required": true,
                        "last_modified": "2013-07-10 19:28:10"
                    },
                    {
                        "id": 6,
                        "template_id": 4,
                        "code": "SPOT",
                        "name": "SPOT",
                        "type": "string",
                        "is_required": true,
                        "last_modified": "2013-07-10 19:28:10"
                    }
                ]
            }
        ],
        "dbg_info": {
            "instance": "28.bm-hbapi.prod.nym1",
            "s1ave_hit": true,
            "db": "141.bm-mysql.prod.nym1",
            "reads": 1,
            "read_limit": 100,
            "read_limit_seconds": 60,
            "writes": 0,
            "write_limit": 60,
            "write_limit_seconds": 60,
            "awesomesauce_cache_used": false,
            "count_cache_used": false,
            "warnings": [],
            "time": 66.461801528931,
            "start_microtime": 1373651335.4519,
            "version": "1.13.52",
            "s1ave_lag": 1,
            "member_last_modified_age": 68896
        }
    }
}
{code}

1 つのクリエイティブカスタム要求テンプレートを表示する

{code}
$ curl -b cookies https://api.appnexus.com/creative-custom-request-template?id=2
{
    "response": {
        "status": "OK",
        "count": 1,
        "start_element": 0,
        "num_elements": 100,
        "creative-custom-request-template": {
            "id": 2,
            "type_id": 3,
            "member_id": 0,
            "media_subtype_id": 1,
            "hostname": "ads.mydas.mobi",
            "uri": "/getAd?apid=#{APID}&auid=${DEVICE_MD5}&ua=${USER_AGENT_ENC}&uip=${USER_IP}&age=${AGE}&gender=${GENDER}&zip=${POSTAL_CODE}&lat=${GEO_LAT}&long=${GEO_LON}",
            "port": 80,
            "is_post": false,
            "content": "",
            "timeout_ms": 200,
            "is_client": false,
            "media_subtype": {
                "id": 1,
                "name": "Standard Banner",
                "media_type_name": "Banner",
                "media_type_id": 1
            },
            "last_modified": "2013-07-10 18:57:43",
            "macros": [
                {
                    "id": 2,
                    "template_id": 2,
                    "code": "APID",
                    "name": "APID",
                    "type": "string",
                    "is_required": true,
                    "last_modified": "2013-07-02 00:50:53"
                }
            ]
        },
        "dbg_info": {
            "instance": "05.hbapi.sand-08.lax1",
            "s1ave_hit": false,
            "db": "master",
            "awesomesauce_cache_used": false,
            "count_cache_used": false,
            "warnings": [],
            "time": 68.688154220581,
            "start_microtime": 1373910064.7161,
            "version": "1.13.53.1",
            "s1ave_miss": "no_service_index",
            "s1ave_lag": 0,
            "member_last_modified_age": 1373910064
        }
    }
}
{code}

要求テンプレートを作成する

要求テンプレートのフィールドを指定する JSON ファイルを作成します。

注:

POSTには、type_id フィールドが必要です。

要求テンプレートの種類の詳細については、「 Creative Custom Request Template Type Service」を参照してください。

{code}
$ cat create.json
{
    "creative-custom-request-template": {
        "hostname": "ads.light-vs-wily.com",
        "uri": "/a/ads?hid_sha1=${DEVICE_SHA1}&idfa=${DEVICE_APPLE_IDA}&enemy=#{ENEMY}&light_or_wily=#{LIGHT_OR_WILY}&megaman_version=#{MEGAMAN_VERSION}&url=${REFERER_URL_ENC}&ua=${USER_AGENT_ENC}&client-ip=${USER_IP}&country=${USER_COUNTRY}&ll=${JUMPTAP_LAT_LONG_ENC}&mt-age=${AGE}&mt-gender=${GENDER}",
        "port": 49995,
        "is_post": false,
        "content": "",
        "timeout_ms": 2,
        "is_client": false,
        "type_id": 1
    }
}
{code}

JSON ペイロードを含む API への POST 呼び出しを行います。

{code}
$ curl -b cookies -X POST -d @create.json https://api.appnexus.com/creative-custom-request-template
{
    "response": {
        "status": "OK",
        "count": 1,
        "start_element": 0,
        "num_elements": 100,
        "creative-custom-request-template": {
            "id": 13,
            "type_id": 1,
            "member_id": 0,
            "media_subtype_id": 1,
            "hostname": "ads.light-vs-wily.com",
            "uri": "/a/ads?hid_sha1=${DEVICE_SHA1}&idfa=${DEVICE_APPLE_IDA}&enemy=#{ENEMY}&light_or_wily=#{LIGHT_OR_WILY}&megaman_version=#{MEGAMAN_VERSION}&url=${REFERER_URL_ENC}&ua=${USER_AGENT_ENC}&client-ip=${USER_IP}&country=${USER_COUNTRY}&ll=${JUMPTAP_LAT_LONG_ENC}&mt-age=${AGE}&mt-gender=${GENDER}",
            "port": 49995,
            "is_post": false,
            "content": "",
            "timeout_ms": 2,
            "is_client": false,
            "media_subtype": {
                "id": 1,
                "name": "Standard Banner",
                "media_type_name": "Banner",
                "media_type_id": 1
            },
            "last_modified": "2013-07-15 19:02:02",
            "macros": ""
        },
        "dbg_info": {
            "instance": "07.hbapi.sand-08.lax1",
            "s1ave_hit": false,
            "db": "master",
            "awesomesauce_cache_used": false,
            "count_cache_used": false,
            "warnings": [],
            "time": 67.02995300293,
            "start_microtime": 1373914957.1776,
            "version": "1.13.53.1",
            "s1ave_miss": "no_service_index",
            "s1ave_lag": 0,
            "member_last_modified_age": 1373914957
        }
    }
}
{code}

要求テンプレートを更新する

まず、更新するパラメーターのみを含む JSON ファイルを作成します。

注:

更新する要求テンプレートの id を含める必要があります。

{code}
$ cat update.json
{"creative-custom-request-template":{"id":13, "type_id":2, "timeout_ms":250}}
{code}

JSON 更新を含め、 PUT 呼び出しを行います。

正常な PUT 呼び出しには、次のものが必要です。

JSON ファイル内の要求テンプレートの ID を指定します。
要求にクエリ文字列パラメーター ( ?id=123 など) を追加しません (下記の例を参照)。

要求テンプレートを削除する

要求を削除するには、クエリ文字列のテンプレート ID が必要です。

{code}
$ curl -b cookies -X DELETE https://api.appnexus.com/creative-custom-request-template?id=123
{code}

次の方法で共有

Creative Custom Request Template サービス

REST API

JSON フィールド

マクロ

メディアサブタイプ

例

すべてのクリエイティブリクエストテンプレートを表示する

1 つのクリエイティブカスタム要求テンプレートを表示する

要求テンプレートを作成する

要求テンプレートを更新する

要求テンプレートを削除する

その他のリソース

次の方法で共有

Creative Custom Request Template サービス

REST API

JSON フィールド

マクロ

メディア サブタイプ

例

すべてのクリエイティブリクエストテンプレートを表示する

1 つのクリエイティブ カスタム要求テンプレートを表示する

要求テンプレートを作成する

要求テンプレートを更新する

要求テンプレートを削除する

関連項目

その他のリソース

メディアサブタイプ

1 つのクリエイティブカスタム要求テンプレートを表示する