配信ラインの管理Manage delivery lines

1 つ以上の配信ラインを作成してインベントリを購入し、プロモーション用の広告キャンペーンの広告を配信するには、Microsoft Store プロモーション API の以下のメソッドを使います。Use these methods in the Microsoft Store promotions API to create one or more delivery lines to buy inventory and deliver your ads for a promotional ad campaign. 配信ラインごとに、ターゲットと入札額を設定できます。また、予算と使用したいクリエイティブへのリンクを設定することで、支払い額を決定できます。For each delivery line, you can set targeting, set your bid price, and decide how much you want to spend by setting a budget and linking to creatives you want to use.

配信ラインと広告キャンペーン、ターゲット プロファイル、クリエイティブとの関係について詳しくは、「Microsoft Store サービスを使用した広告キャンペーンの実行」をご覧ください。For more information about the relationship between delivery lines and ad campaigns, targeting profiles, and creatives, see Run ad campaigns using Microsoft Store services.

Note   メモ  この API を使用して広告キャンペーンの配信明細行を正常に作成するには、まず、パートナーセンターの [ ad キャンペーン] ページを使用して1つの有料広告キャンペーンを作成し、このページで少なくとも1つの支払い方法を追加する必要があります。Note  Before you can successfully create delivery lines for ad campaigns using this API, you must first create one paid ad campaign using the Ad campaigns page in Partner Center, and you must add at least one payment instrument on this page. これを行うと、この API を使用して、広告キャンペーンの請求可能な配信ラインを正しく作成することができます。After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. API を使用して作成した ad キャンペーンは、パートナーセンターの [ ad キャンペーン ] ページで選択した既定の支払い方法に自動的に課金されます。Ad campaigns you create using the API will automatically bill the default payment instrument chosen on the Ad campaigns page in Partner Center.

前提条件Prerequisites

これらのメソッドを使うには、最初に次の作業を行う必要があります。To use these methods, you need to first do the following:

  • Microsoft Store プロモーション API に関するすべての前提条件を満たします (前提条件がまだ満たされていない場合)。If you have not done so already, complete all the prerequisites for the Microsoft Store promotions API.

    注意

    前提条件の一部として、 パートナーセンターで少なくとも1つの有料広告キャンペーンを作成 し、パートナーセンターで広告キャンペーンの少なくとも1つの支払い方法を追加するようにしてください。As part of the prerequisites, be sure that you create at least one paid ad campaign in Partner Center and that you add at least one payment instrument for the ad campaign in Partner Center. この API を使用して作成した配信行は、パートナーセンターの [ Ad キャンペーン ] ページで選択した既定の支払い方法に自動的に課金されます。Delivery lines you create using this API will automatically bill the default payment instrument chosen on the Ad campaigns page in Partner Center.

  • これらのメソッドの要求ヘッダーで使う Azure AD アクセス トークンを取得します。Obtain an Azure AD access token to use in the request header for these methods. アクセス トークンを取得した後、アクセス トークンを使用できるのは、その有効期限が切れるまでの 60 分間です。After you obtain an access token, you have 60 minutes to use it before it expires. トークンの有効期限が切れたら新しいトークンを取得できます。After the token expires, you can obtain a new one.

RequestRequest

これらのメソッドでは、次の URL が使用されます。These methods have the following URIs.

メソッドの型Method type 要求 URIRequest URI 説明Description
POSTPOST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line 新しい配信ラインを作成します。Creates a new delivery line.
PUTPUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} lineId により指定された配信ラインを編集します。Edits the delivery line specified by lineId.
GETGET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} lineId により指定された配信ラインを取得します。Gets the delivery line specified by lineId.
HeaderHeader TypeType 説明Description
承認Authorization stringstring 必須。Required. ベアラートークン形式の Azure AD アクセストークンBearer < token > 。The Azure AD access token in the form Bearer <token>.
追跡 IDTracking ID GUIDGUID 任意。Optional. 呼び出しフローを追跡する ID。An ID that tracks the call flow.

要求本文Request body

POST メソッドと PUT メソッドには、配信ライン オブジェクトの必須フィールドと設定または変更する追加フィールドを持つ JSON 要求本文が必要です。The POST and PUT methods require a JSON request body with the required fields of a Delivery line object and any additional fields you want to set or change.

要求の例Request examples

次の例は、POST メソッドを呼び出して配信ラインを作成する方法を示しています。The following example demonstrates how to call the POST method to create a delivery line.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign - Paid Line",
    "configuredStatus": "Active",
    "startDateTime": "2017-01-19T12:09:34Z",
    "endDateTime": "2017-01-31T23:59:59Z",
    "bidAmount": 0.4,
    "dailyBudget": 20,
    "targetProfileId": {
        "id": 310021746
    },
    "creatives": [
        {
            "id": 106851
        }
    ],
    "campaignId": 31043481,
    "minMinutesPerImp ": 1
}

次の例は、GET メソッドを呼び出して配信ラインを取得する方法を示しています。The following example demonstrates how to call the GET method to retrieve a delivery line.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/31019990  HTTP/1.1
Authorization: Bearer <your access token>

[応答]Response

これらのメソッドは、作成、更新、または取得された配信ラインに関する情報を含む配信ライン オブジェクトを持つ JSON 応答本文を返します。These methods return a JSON response body with a Delivery line object that contains information about the delivery line that was created, updated, or retrieved. これらのメソッドの応答本文を次の例に示します。The following example demonstrates a response body for these methods.

{
    "Data": {
        "id": 31043476,
        "name": "Contoso App Campaign - Paid Line",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "startDateTime": "2017-01-19T12:09:34Z",
        "endDateTime": "2017-01-31T23:59:59Z",
        "createdDateTime": "2017-01-17T10:28:34Z",
        "bidType": "CPM",
        "bidAmount": 0.4,
        "dailyBudget": 20,
        "targetProfileId": {
            "id": 310021746
        },
        "creatives": [
            {
                "id": 106126
            }
        ],
        "campaignId": 31043481,
        "minMinutesPerImp ": 1,
        "pacingType ": "SpendEvenly",
        "currencyId ": 732
    }
}

配信ライン オブジェクトDelivery line object

これらのメソッドの要求本文と応答本文には、次のフィールドが含まれています。The request and response bodies for these methods contain the following fields. この表は、読み取り専用のフィールド (つまり、PUT メソッドで変更できない) と POST メソッドまたは PUT メソッドの要求本文で必須のフィールドを示しています。This table shows which fields are read-only (meaning that they cannot be changed in the PUT method) and which fields are required in the request body for the POST or PUT methods.

フィールドField TypeType 説明Description 読み取り専用Read only DefaultDefault POST/PUT に必須かどうかRequired for POST/PUT
idid 整数 (integer)integer 配信ラインの ID です。The ID of the delivery line. はいYes いいえNo
namename stringstring 配信ラインの名前です。The name of the delivery line. いいえNo POSTPOST
configuredStatusconfiguredStatus stringstring 開発者により指定された配信ラインのステータスを指定する次のいずれかの値です。One of the following values that specifies the status of the delivery line specified by the developer:
  • アクティブActive
  • 非アクティブInactive
いいえNo POSTPOST
effectiveStatuseffectiveStatus stringstring システム検証に基づいて配信ラインの有効ステータスを指定する次のいずれかの値です。One of the following values that specifies the effective status of the delivery line based on system validation:
  • アクティブActive
  • 非アクティブInactive
  • 処理中Processing
  • FailedFailed
はいYes いいえNo
effectiveStatusReasonseffectiveStatusReasons arrayarray 配信ラインの有効ステータスの理由を指定する次のうち 1 つ以上の値です。One or more of the following values that specify the reason for the effective status of the delivery line:
  • AdCreativesInactiveAdCreativesInactive
  • ValidationFailedValidationFailed
はいYes いいえNo
startDatetimestartDatetime stringstring 配信ラインの開始日時です (ISO 8601 形式)。The start date and time for the delivery line, in ISO 8601 format. 日時が過去の場合、この値を変更できません。This value cannot be changed if it is already in the past. いいえNo POST、PUTPOST, PUT
endDatetimeendDatetime stringstring 配信ラインの終了日時です (ISO 8601 形式)。The end date and time for the delivery line, in ISO 8601 format. 日時が過去の場合、この値を変更できません。This value cannot be changed if it is already in the past. いいえNo POST、PUTPOST, PUT
createdDatetimecreatedDatetime stringstring 配信ラインが作成された日時 (ISO 8601 形式)。The date and time the delivery line was created, in ISO 8601 format. はいYes いいえNo
bidTypebidType stringstring 配信ラインの入札の種類を指定する値です。A value that specifies the bidding type of the delivery line. 現時点では、サポートされている唯一の値は CPM です。Currently, the only supported value is CPM. いいえNo CPMCPM いいえNo
bidAmountbidAmount decimaldecimal 広告要求の入札に使う入札額です。The bid amount to be used for bidding any ad request. いいえNo 対象市場に基づく平均 CPM 値です (この値は定期的に変更されます)。The average CPM value based on target markets (this value is revised periodically). いいえNo
dailyBudgetdailyBudget decimaldecimal 配信ラインの 1 日あたりの予算です。The daily budget for the delivery line. dailyBudget または lifetimeBudget を設定する必要があります。Either dailyBudget or lifetimeBudget must be set. いいえNo POST、PUT (lifetimeBudget が設定されていない場合)POST, PUT (if lifetimeBudget is not set)
lifetimeBudgetlifetimeBudget decimaldecimal 配信ラインの全体予算です。The lifetime budget for the delivery line. lifetimeBudget* または dailyBudget を設定する必要があります。Either lifetimeBudget* or dailyBudget must be set. いいえNo POST、PUT (dailyBudget が設定されていない場合)POST, PUT (if dailyBudget is not set)
targetingProfileIdtargetingProfileId objectobject この配信ラインを対象にするユーザー、地域、およびインベントリの種類を指定するターゲット プロファイルを識別するオブジェクトです。On object that identifies the targeting profile that describes the users, geographies and inventory types that you want to target for this delivery line. このオブジェクトは、ターゲット プロファイルの ID を指定する単一の id フィールドで構成されます。This object consists of a single id field that specifies the ID of the targeting profile. いいえNo いいえNo
creativescreatives arrayarray 配信ラインに関連づけられたクリエイティブを表す 1 つ以上のオブジェクトです。One or more objects that represent the creatives that are associated with the delivery line. このフィールド内の各オブジェクトは、クリエイティブの ID を指定する単一の id フィールドで構成されます。Each object in this field consists of a single id field that specifies the ID of a creative. いいえNo いいえNo
campaignIdcampaignId 整数 (integer)integer 親広告キャンペーンの ID です。The ID of the parent ad campaign. いいえNo いいえNo
minMinutesPerImpminMinutesPerImp 整数 (integer)integer この配信ラインから同じユーザーに表示される 2 つのインプレッション間の間隔 (分単位) を指定します。Specifies the minimum time interval (in minutes) between two impressions shown to the same user from this delivery line. いいえNo 40004000 いいえNo
pacingTypepacingType stringstring ペーシングの種類を指定する次のいずれかの値です。One of the following values that specify the pacing type:
  • SpendEvenlySpendEvenly
  • SpendAsFastAsPossibleSpendAsFastAsPossible
いいえNo SpendEvenlySpendEvenly いいえNo
currencyIdcurrencyId 整数 (integer)integer キャンペーンの通貨の ID です。The ID of the currency of the campaign. はいYes 開発者アカウントの通貨 (POST または PUT 呼び出しではこのフィールドを指定する必要はありません)The currency of the developer account (you do not need to specify this field in POST or PUT calls) いいえNo