通过

管理广告活动

  • 项目

在 Microsoft Store 促销 API 中使用这些方法来创建、编辑和获取适合你的应用的促销性广告活动。 使用此方法创建的每个活动只能与一个应用关联。

注意 还可以使用合作伙伴中心创建和管理广告市场活动，你以编程方式创建的市场活动可以在合作伙伴中心访问。 有关在合作伙伴中心中管理广告活动的详细信息，请参阅为你的应用创建广告活动。

使用这些方法创建或更新活动时，你通常还需要调用以下一种或多种方法来管理与活动关联的投放渠道、目标市场配置文件和创意。 有关活动与投放渠道、目标市场配置文件和创意之间关系的详细信息，请参阅使用 Microsoft Store 服务开展广告活动。

先决条件

若要使用这些方法，首先需要执行以下操作：

  • 如果尚未开始操作，请先完成 Microsoft Store 促销 API 的所有先决条件。

    注意 作为先决条件的一部分，请务必在合作伙伴中心创建至少一个付费广告活动，并在合作伙伴中心为广告活动添加至少一种付款方式。 使用此 API 创建的广告活动的投放渠道将按照在合作伙伴中心中的“广告市场活动”页中选择的默认付款方式自动进行计费。

  • 获取 Azure AD 访问令牌，以供在这些方法的请求标头中使用。 获取访问令牌后，在它到期前，你有 60 分钟的使用时间。 该令牌到期后，可以获取新的令牌。

请求

这些方法具有以下 URI。

方法类型 请求 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 查询广告活动。 请参阅参数部分了解支持的查询参数。
标头 类型 说明
授权 字符串 必需。 Azure AD 访问令牌的格式为 Bearertoken<>。
跟踪 ID GUID 可选。 跟踪调用流的 ID。

 

parameters

用于查询广告活动的 GET 方法支持以下可选的查询参数。

名称 Type 说明
skip int 要在查询中跳过的行数。 使用此参数分页浏览数据集。 例如，fetch=10 和 skip=0，将检索前 10 行数据；top=10 和 skip=10，将检索之后的 10 行数据，依此类推。
“etch int 要在请求中返回的数据行数。
campaignSetSortColumn string 将响应正文中的活动对象按指定字段排序。 语法为 CampaignSetSortColumn=field，其中的 field 参数可以是以下字符串之一：

  • id
  • createdDateTime

默认为 createdDateTime。
isDescending 布尔 将响应正文中的活动对象按升序或降序排列。
storeProductId string 使用此值只返回与具有指定应用商店 ID 的应用关联的广告活动。 产品应用商店 ID 示例：9nblggh42cfd。
label string 使用此值只返回包含在活动对象中指定的 label 的广告活动。

请求正文

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>

响应

这些方法返回一个 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"
            }
        ]
    }
}

活动对象

这些方法的请求和响应正文包含以下字段。 这张表列出了 POST 方法请求正文中的哪些字段是只读字段（意味着不能在 PUT 方法中更改它们）以及哪些字段是必填字段。

字段 类型​​ 说明 只读 默认 POST 必填字段
id integer 广告市场活动的 ID。 是 否
name string 广告活动的名称。 否 是
configuredStatus string 以下值之一，指定开发人员指定的广告市场活动的状态：
  • 活动
  • 非活动
 否 可用 是
effectiveStatus string 以下值之一，指定基于系统验证的广告市场活动的有效状态：
  • 活动
  • 非活动
  • Processing
 是 否
effectiveStatusReasons array 以下一个或多个值，指定广告市场活动的有效状态的原因：
  • AdCreativesInactive
  • BillingFailed
  • AdLinesInactive
  • ValidationFailed
  • 已失败
 是 否
storeProductId string 与广告活动关联的应用的应用商店 ID。 产品应用商店 ID 示例：9nblggh42cfd。 是 是
标签 array 一个或多个字符串，代表活动的自定义标签。 这些标签用于搜索和标记活动。 否 Null 否
type string 指定市场活动类型的以下值之一：
  • 已付
  • 楼宅
  • 社区
 是 是
目标 string 以下值之一，指定市场活动的目标：
  • DriveInstall
  • DriveReengagement
  • DriveInAppPurchase
 否 DriveInstall 是
lines array 标识与广告活动关联的投放渠道的一个或多个对象。 此字段中的每个对象都由 id 和 name（分别指定投放渠道的 ID 和名称）字段组成。 否 否
createdDate string 广告活动的创建日期和时间（ISO 8601 格式）。 是 否