次の方法で共有

広告キャンペーンの管理

  • [アーティクル]

アプリのプロモーション用の広告キャンペーンを作成、編集、取得するには、Microsoft Store プロモーション API の以下のメソッドを使います。 このメソッドを使って作成した各キャンペーンに関連付けることができるのは、1 つのアプリのみです。

注 パートナー センターを使用して広告キャンペーンを作成し、管理することもできます。プログラムにより作成したキャンペーンには、パートナー センターからアクセスできます。 パートナー センターでの広告キャンペーンの管理について詳しくは、アプリ向けの広告キャンペーンの作成に関するページをご覧ください。

これらのメソッドを使ってキャンペーンを作成または更新する場合、通常は以下のメソッドも 1 つ以上呼び出し、キャンペーンに関連付けられた配信ライン、ターゲット プロファイル、クリエイティブを管理します。 キャンペーン、配信ライン、ターゲット プロファイル、クリエイティブ間の関係について詳しくは、「Microsoft Store サービスを使用した広告キャンペーンの実行」をご覧ください。

前提条件

これらのメソッドを使うには、最初に次の作業を行う必要があります。

  • Microsoft Store プロモーション API に関するすべての前提条件を満たします (前提条件がまだ満たされていない場合)。

    注 前提条件の一部として、パートナー センターで有料の広告キャンペーンを少なくとも 1 つ作成する必要があります。また、パートナー センターで、広告キャンペーンの支払い方法を少なくとも 1 つ追加する必要があります。 この API を使用して作成した広告キャンペーンの配信ラインでは、パートナー センターの [広告キャンペーン] ページで選んだ既定の支払い方法に対して自動的に請求が行われます。

  • これらのメソッドの要求ヘッダーで使う Azure AD アクセス トークンを取得します。 アクセス トークンを取得した後、アクセス トークンを使用できるのは、その有効期限が切れるまでの 60 分間です。 トークンの有効期限が切れたら新しいトークンを取得できます。

要求

これらのメソッドでは、次の URL が使用されます。

メソッドの型 要求 URI 説明
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign 新しい広告キャンペーンを作成します。
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} campaignId により指定された広告キャンペーンを編集します。
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} campaignId により指定された広告キャンペーンを取得します。
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign 広告キャンペーンのクエリ。 サポートされるクエリ パラメーターの「パラメーター」セクションをご覧ください。
ヘッダー 種類 説明
承認 string 必須。 Bearer<トークン> という形式の Azure AD アクセス トークン。
追跡 ID GUID 省略可能。 呼び出しフローを追跡する ID。

 

パラメーター

広告キャンペーンを問い合わせる GET メソッドは、次のオプション クエリ パラメーターをサポートします。

名前 種類 説明
skip int クエリでスキップする行数です。 データ セットを操作するには、このパラメーターを使用します。 たとえば、fetch=10 と skip=0 を指定すると、データの最初の 10 行が取得され、top=10 と skip=10 を指定すると、データの次の 10 行が取得されます。
fetch int 要求で返すデータの行数です。
campaignSetSortColumn string 応答本文で、指定されたフィールドによりキャンペーン オブジェクトを順序付けます。 構文は CampaignSetSortColumn=field です。ここで、field パラメーターは次のいずれかの文字列になります。

  • id
  • createdDateTime

既定値は createdDateTime です。
isDescending ブール値 応答本文で、キャンペーン オブジェクトを降順または昇順で並べ替えます。
storeProductId string 指定されたストア ID を持つアプリに関連付けられた広告キャンペーンのみ返す場合は、この値を使います。 製品のストア ID の例は、9nblggh42cfd です。
label string キャンペーン オブジェクトに指定されたラベルが含まれる広告キャンペーンのみ返す場合は、この値を使います。

要求本文

POST メソッドと PUT メソッドには、キャンペーン オブジェクトの必須フィールドと設定または変更する追加フィールドを持つ JSON 要求本文が必要です。

要求例

次の例は、POST メソッドを呼び出して広告キャンペーンを作成する方法を示しています。

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 メソッドを呼び出して特定の広告キャンペーンを取得する方法を示しています。

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

次の例は、GET メソッドを呼び出して、作成日により並べ替えられた一連の広告キャンペーンを問い合わせる方法を示しています。

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 応答本文を返します。 次の例は、特定のキャンペーンの GET メソッドの応答本文を示しています。

{
    "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"
            }
        ]
    }
}

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

これらのメソッドの要求本文と応答本文には、次のフィールドが含まれています。 この表は、読み取り専用のフィールド (つまり、PUT メソッドで変更できない) と POST メソッドの要求本文で必須のフィールドを示しています。

フィールド Type 説明 読み取り専用 Default POST に必須かどうか
ID 整数 (integer) 広告キャンペーンの ID です。 はい いいえ
name string 広告キャンペーンの名前です。 いいえ はい
configuredStatus string 開発者により指定された広告キャンペーンのステータスを指定する次のいずれかの値です。
  • アクティブ
  • 非アクティブ
 No アクティブ はい
effectiveStatus string システム検証に基づいて広告キャンペーンの有効ステータスを指定する次のいずれかの値です。
  • アクティブ
  • 非アクティブ
  • 処理
 はい いいえ
effectiveStatusReasons array 広告キャンペーンの有効ステータスの理由を指定する次のうち 1 つ以上の値です。
  • AdCreativesInactive
  • BillingFailed
  • AdLinesInactive
  • ValidationFailed
  • Failed
 はい いいえ
storeProductId string この広告キャンペーンが関連付けられているアプリのストア ID です。 製品のストア ID の例は、9nblggh42cfd です。 はい はい
labels array キャンペーンのカスタム ラベルを表す 1 つ以上の文字列です。 これらのラベルは、キャンペーンの検索とタグ付けに使われます。 No null いいえ
type string キャンペーンの種類を指定する次のいずれかの値です。
  • 有料
  • 自社
  • コミュニティ
 はい はい
objective string キャンペーンの目的を指定する次のいずれかの値です。
  • DriveInstall
  • DriveReengagement
  • DriveInAppPurchase
 No DriveInstall はい
lines array 広告キャンペーンに関連づけられた配信ラインを識別する 1 つ以上のオブジェクトです。 このフィールドの各オブジェクトは、配信ラインの ID と名前を指定する id フィールドと name フィールドで構成されます。 いいえ いいえ
createdDate string 広告キャンペーンが作成された日時 (ISO 8601 形式)。 はい いいえ