広告キャンペーンの管理Manage ad campaigns

アプリのプロモーション用の広告キャンペーンを作成、編集、取得するには、Microsoft Store プロモーション API の以下のメソッドを使います。Use these methods in the Microsoft Store promotions API to create, edit and get promotional ad campaigns for your app. このメソッドを使って作成した各キャンペーンに関連付けることができるのは、1 つのアプリのみです。Each campaign you create using this method can be associated with only one app.

Note   メモ  パートナーセンターを使用して広告キャンペーンを作成および管理することもできます。また、プログラムによって作成するキャンペーンは、パートナーセンターでアクセスできます。Note  You can also create and manage ad campaigns using Partner Center, and campaigns that you create programmatically can be accessed in Partner Center. パートナーセンターで ad キャンペーンを管理する方法の詳細については、「 アプリの ad キャンペーンを作成する」を参照してください。For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

これらのメソッドを使ってキャンペーンを作成または更新する場合、通常は以下のメソッドも 1 つ以上呼び出し、キャンペーンに関連付けられた配信ラインターゲット プロファイルクリエイティブを管理します。When you use these methods to create or update a campaign, you typically also call one or more of the following methods to manage the delivery lines, targeting profiles, and creatives that are associated with the campaign. キャンペーン、配信ライン、ターゲット プロファイル、クリエイティブ間の関係について詳しくは、「Microsoft Store サービスを使用した広告キャンペーンの実行」をご覧ください。For more information about the relationship between campaigns, delivery lines, targeting profiles, and creatives, see Run ad campaigns using Microsoft Store services.

前提条件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.

    Note   メモ  前提条件の一部として、パートナーセンターで少なくとも1つの有料広告キャンペーンを作成し、パートナーセンターで広告キャンペーンの少なくとも1つの支払い方法を追加するようにしてください。Note  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 for ad campaigns 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/campaign 新しい広告キャンペーンを作成します。Creates a new ad campaign.
PUTPUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} campaignId により指定された広告キャンペーンを編集します。Edits the ad campaign specified by campaignId.
GETGET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} campaignId により指定された広告キャンペーンを取得します。Gets the ad campaign specified by campaignId.
GETGET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign 広告キャンペーンのクエリ。Queries for ad campaigns. サポートされるクエリ パラメーターの「パラメーター」セクションをご覧ください。See the Parameters section for the supported query parameters.
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.

 

パラメーターParameters

広告キャンペーンを問い合わせる GET メソッドは、次のオプション クエリ パラメーターをサポートします。The GET method to query for ad campaigns supports the following optional query parameters.

名前Name TypeType 説明Description
skipskip intint クエリでスキップする行数です。The number of rows to skip in the query. データ セットを操作するには、このパラメーターを使用します。Use this parameter to page through data sets. たとえば、fetch=10 と skip=0 を指定すると、データの最初の 10 行が取得され、top=10 と skip=10 を指定すると、データの次の 10 行が取得されます。For example, fetch=10 and skip=0 retrieves the first 10 rows of data, top=10 and skip=10 retrieves the next 10 rows of data, and so on.
fetchfetch intint 要求で返すデータの行数です。The number of rows of data to return in the request.
campaignSetSortColumncampaignSetSortColumn stringstring 応答本文で、指定されたフィールドによりキャンペーン オブジェクトを順序付けます。Orders the Campaign objects in the response body by the specified field. 構文は CampaignSetSortColumn=field です。ここで、field パラメーターは次のいずれかの文字列になります。The syntax is CampaignSetSortColumn=field, where the field parameter can be one of the following strings:

  • idid
  • createdDateTimecreatedDateTime

既定値は createdDateTime です。The default is createdDateTime.

isDescendingisDescending ブール型Boolean 応答本文で、キャンペーン オブジェクトを降順または昇順で並べ替えます。Sorts the Campaign objects in the response body in descending or ascending order.
storeProductIdstoreProductId stringstring 指定されたストア ID を持つアプリに関連付けられた広告キャンペーンのみ返す場合は、この値を使います。Use this value to return only the ad campaigns that are associated with the app with the specified Store ID. 製品のストア ID の例は、9nblggh42cfd です。An example Store ID for a product is 9nblggh42cfd.
labellabel stringstring キャンペーン オブジェクトに指定されたラベルが含まれる広告キャンペーンのみ返す場合は、この値を使います。Use this value to return only the ad campaigns that include the specified label in the Campaign object.

要求本文Request body

POST メソッドと PUT メソッドには、キャンペーン オブジェクトの必須フィールドと設定または変更する追加フィールドを持つ JSON 要求本文が必要です。The POST and PUT methods require a JSON request body with the required fields of a Campaign 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 an ad campaign.

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

{
    "name": "Contoso App Campaign",
    "storeProductId": "9nblggh42cfd",
    "configuredStatus": "Active",
    "objective": "DriveInstalls",
    "type": "Community"
}

次の例は、GET メソッドを呼び出して特定の広告キャンペーンを取得する方法を示しています。The following example demonstrates how to call the GET method to retrieve a specific ad campaign.

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

次の例は、GET メソッドを呼び出して、作成日により並べ替えられた一連の広告キャンペーンを問い合わせる方法を示しています。The following example demonstrates how to call the GET method to query for a set of ad campaigns, sorted by the created date.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?storeProductId=9nblggh42cfd&fetch=100&skip=0&campaignSetSortColumn=createdDateTime HTTP/1.1
Authorization: Bearer <your access token>

[応答]Response

これらのメソッドは、呼び出したメソッドに応じて 1 つ以上のキャンペーン オブジェクトを含む JSON 応答本文を返します。These methods return a JSON response body with one or more Campaign objects, depending on the method you called. 次の例は、特定のキャンペーンの GET メソッドの応答本文を示しています。The following example demonstrates a response body for the GET method for a specific campaign.

{
    "Data": {
        "id": 31043481,
        "name": "Contoso App Campaign",
        "createdDate": "2017-01-17T10:12:15Z",
        "storeProductId": "9nblggh42cfd",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "labels": [],
        "objective": "DriveInstalls",
        "type": "Paid",
        "lines": [
            {
                "id": 31043476,
                "name": "Contoso App Campaign - Paid Line"
            }
        ]
    }
}

キャンペーン オブジェクトCampaign object

これらのメソッドの要求本文と応答本文には、次のフィールドが含まれています。The request and response bodies for these methods contain the following fields. この表は、読み取り専用のフィールド (つまり、PUT メソッドで変更できない) と POST メソッドの要求本文で必須のフィールドを示しています。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 method.

フィールドField TypeType 説明Description 読み取り専用Read only DefaultDefault POST に必須かどうかRequired for POST
idid 整数 (integer)integer 広告キャンペーンの ID です。The ID of the ad campaign. はいYes いいえNo
namename stringstring 広告キャンペーンの名前です。The name of the ad campaign. いいえNo はいYes
configuredStatusconfiguredStatus stringstring 開発者により指定された広告キャンペーンのステータスを指定する次のいずれかの値です。One of the following values that specifies the status of the ad campaign specified by the developer:
  • アクティブActive
  • 非アクティブInactive
いいえNo アクティブActive はいYes
effectiveStatuseffectiveStatus stringstring システム検証に基づいて広告キャンペーンの有効ステータスを指定する次のいずれかの値です。One of the following values that specifies the effective status of the ad campaign based on system validation:
  • アクティブActive
  • 非アクティブInactive
  • 処理中Processing
はいYes いいえNo
effectiveStatusReasonseffectiveStatusReasons arrayarray 広告キャンペーンの有効ステータスの理由を指定する次のうち 1 つ以上の値です。One or more of the following values that specify the reason for the effective status of the ad campaign:
  • AdCreativesInactiveAdCreativesInactive
  • BillingFailedBillingFailed
  • AdLinesInactiveAdLinesInactive
  • ValidationFailedValidationFailed
  • FailedFailed
はいYes いいえNo
storeProductIdstoreProductId stringstring この広告キャンペーンが関連付けられているアプリのストア ID です。The Store ID for the app that this ad campaign is associated with. 製品のストア ID の例は、9nblggh42cfd です。An example Store ID for a product is 9nblggh42cfd. はいYes はいYes
labelslabels arrayarray キャンペーンのカスタム ラベルを表す 1 つ以上の文字列です。One or more strings that represent custom labels for the campaign. これらのラベルは、キャンペーンの検索とタグ付けに使われます。These labels be used for searching and tagging campaigns. いいえNo nullnull いいえNo
typetype stringstring キャンペーンの種類を指定する次のいずれかの値です。One of the following values that specifies the campaign type:
  • 支払い済みPaid
  • House
  • コミュニティCommunity
はいYes はいYes
objectiveobjective stringstring キャンペーンの目的を指定する次のいずれかの値です。One of the following values that specifies the objective of the campaign:
  • DriveInstallDriveInstall
  • DriveReengagementDriveReengagement
  • DriveInAppPurchaseDriveInAppPurchase
いいえNo DriveInstallDriveInstall はいYes
lineslines arrayarray 広告キャンペーンに関連づけられた配信ラインを識別する 1 つ以上のオブジェクトです。One or more objects that identify the delivery lines that are associated with the ad campaign. このフィールドの各オブジェクトは、配信ラインの ID と名前を指定する id フィールドと name フィールドで構成されます。Each object in this field consists of an id and name field that specifies the ID and name of the delivery line. いいえNo いいえNo
createdDatecreatedDate stringstring 広告キャンペーンが作成された日時 (ISO 8601 形式)。The date and time the ad campaign was created, in ISO 8601 format. はいYes いいえNo