共用方式為

管理廣告播送行

  • 發行項

使用 Microsoft Store 促銷 API 中的這些方法，建立一或多個廣告播送行來購買庫存，並為您的促銷廣告行銷活動提供廣告。 針對每一個廣告播送行，您可以設定受眾、設定出價價格，以及設定預算來決定您想要花費多少費用，並連結到您想要使用的廣告創意內容。

有關廣告播送行、廣告行銷活動、受眾設定檔和創意內容之間的關係詳細資訊，請參閱使用 Microsoft Store 服務執行廣告行銷活動。

注意：您必須先使用合作夥伴中心的 [廣告行銷活動] 頁面建立一個付費廣告行銷活動，而且您必須在此頁面上新增至少一個付款方式，才能成功建立並開始廣告行銷活動。 完成此動作之後，您將能夠使用此 API 成功為廣告行銷活動建立可計費的廣告播送行。 您使用 API 建立的廣告行銷活動會自動向合作夥伴中心的 [廣告行銷活動] 頁面上選擇的預設付款方式計費。

必要條件

若要使用這些方法，您必須先執行下列動作：

  • 如果您尚未這麼做，請完成 Microsoft Store 促銷 API 的所有必要條件。

    注意

    先決條件之一為請務必在合作夥伴中心建立至少一個付費廣告行銷活動，並在合作夥伴中心新增至少一個廣告行銷活動的付款方式。 您使用此 API 建立的廣告播送行，會自動向合作夥伴中心的 [廣告行銷活動] 頁面上選擇的預設付款方式計費。

  • 取得 Azure AD 存取權杖，以用於這些方法的要求標頭中。 取得存取權杖之後，您在其到期之前有 60 分鐘的時間可以使用。 權杖到期之後，您可以取得新的權杖。

要求

這些方法具有下列 URI。

方法類型 要求 URI 描述
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line 建立新的廣告播送行。
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} 編輯 lineId 所指定的廣告播送行。
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} 取得 lineId 所指定的廣告播送行。
標題 類型 描述
授權 字串 必要。 持有人<權杖>形式的Azure AD 存取權杖。
追蹤 ID GUID 選擇性。 追蹤呼叫流程的識別碼。

要求本文

POST 和 PUT 方法需要一個 JSON 要求本文，其中包含廣告播送行物件的必填欄位以及要設置或更改的任何其他欄位。

要求範例

下面的範例示範如何呼叫 POST 方法來建立廣告播送行。

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 方法來擷取廣告播送行。

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

回應

這些方法返回一個 JSON 回應正文，其中包含廣告播送行物件，該物件包含有關已建立、更新或擷取的廣告播送行資訊。 下列範例示範這些方法的回應本文。

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

廣告播送行物件

這些方法的要求和回應本文包含下欄欄位。 下列資料表顯示了哪些欄位是唯讀的 (這意味著無法在 PUT 方法中更改)，以及 POST 或 PUT 方法的要求正文中需要哪些欄位。

欄位 類型 描述 唯讀 預設 對 POST/PUT 是否必要
id 整數 廣告播送行的識別碼。 是 No
NAME 字串 廣告播送行的名稱。 No POST
configuredStatus 字串 下列其中一個值，指定開發人員所指定廣告播送行的狀態：
  • 使用中
  • 非使用中
 No POST
effectiveStatus 字串 下列其中一個值，可根據系統驗證指定廣告播送行的有效狀態：
  • 使用中
  • 非使用中
  • 正在處理
  • 失敗
 是 No
effectiveStatusReasons 陣列 下列一或多個值，指定廣告播送行有效狀態的原因：
  • AdCreativesInactive
  • ValidationFailed
 是 No
startDatetime 字串 廣告播送行的開始日期和時間，格式為 ISO 8601。 如果此值已經過去，則無法變更此值。 No POST、PUT
endDatetime 字串 廣告播送行的結束日期和時間，格式為 ISO 8601。 如果此值已經過去，則無法變更此值。 No POST、PUT
createdDatetime 字串 廣告播送行的建立日期和時間，格式為 ISO 8601。 是 No
bidType 字串 指定廣告播送的投標類型值。 目前唯一支援的值是 CPM。 No CPM No
bidAmount decimal 要用於投標任何廣告要求的投標金額。 No 以目標市場為基礎的平均 CPM 值 (此值會定期修訂)。 No
dailyBudget decimal 廣告播送行的每日預算。 必須設定 dailyBudget 或 lifetimeBudget。 No POST、PUT (如果未設定 lifetimeBudget)
lifetimeBudget decimal 廣告播送行的存留期預算。 必須設定 lifetimeBudget* 或 dailyBudget。 No POST、PUT (如果未設定 dailyBudget)
targetingProfileId object 在識別受眾設定檔的物件上， 會描述您要針對此廣告播送行要鎖定的使用者、地理位置和庫存類型。 這個物件是由單一 id欄位所組成，指定受眾設定檔的識別碼。 No No
creatives 陣列 一或多個物件，代表與廣告播送行相關聯的創意內容。 此欄位中的每個物件都包含單一 id欄位，指定創意內容的識別碼。 No No
campaignId 整數 父系廣告行銷活動的識別碼。 No No
minMinutesPerImp 整數 指定從這個廣告播送行向相同使用者顯示的兩個印象之間的最小時間間隔 (以分鐘為單位)。 No 4000 No
pacingType 字串 下列其中一個值，指定步調類型：
  • SpendEvenly
  • SpendAsFastAsPossible
 No SpendEvenly No
currencyId 整數 行銷活動貨幣的識別碼。 Yes 開發人員帳戶的貨幣 (您不需要在 POST 或 PUT 呼叫中指定此欄位) No