管理交付线

2025-06-10

在 Microsoft Store 促销 API 中使用这些方法来创建一个或多个 投放线，，用于购买库存和投放促销广告活动的广告。对于每个交付线，你可以设置目标、设置出价价格，并通过设置预算并链接到要使用的创意来决定要花费多少。

有关投放线路与广告活动、目标配置文件和创意之间关系的详细信息，请参阅使用Microsoft Store服务运行广告活动。

注意在成功使用此 API 为广告活动创建投放线路之前，必须 先使用合作伙伴中心的广告活动页面创建一个付费广告活动，并且必须在该页面上至少添加一个付款方式。执行此操作后，你将能够使用此 API 成功为广告市场活动创建可计费的投放渠道。使用 API 创建的广告市场活动将自动对合作伙伴中心 广告市场活动 页上选择的默认付款方式计费。

先决条件

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

如果尚未这样做，请完成 Microsoft Store 促销 API 的所有先决条件。

注释

作为先决条件的一部分，请确保在合作伙伴中心至少创建一个付费广告市场活动，并在合作伙伴中心为广告市场活动添加至少一个付款方式。使用此 API 创建的配送线将在合作伙伴中心 广告活动 页上选择的默认支付方式上自动计费。
获取 Azure AD 访问令牌，以便在这些方法的请求标头中使用。获取访问令牌后，在它到期前，你有 60 分钟的使用时间。令牌过期后，可以获取一个新令牌。

请求

这些方法具有以下 URI。

方法类型	请求 URI	DESCRIPTION
帖子	`https://manage.devcenter.microsoft.com/v1.0/my/promotion/line`	创建新的交付线。
放置	`https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId}`	编辑由 lineId指定的传递线。
获取	`https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId}`	获取由 lineId指定的传输线路。

标题	类型	DESCRIPTION
授权	字符串	必填。 Azure AD 访问令牌，形式为Bearer<token>。
跟踪识别码	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 方法的请求正文中需要哪些字段。

领域	类型	DESCRIPTION	只读	违约	必须用于 POST/PUT
身份证	整数	配送线的 ID。	是的		否
姓名	字符串	配送线路的名称。	否		帖子
configuredStatus	字符串	以下值之一，指定开发人员指定的交付线的状态：积极非活动	否		帖子
effectiveStatus	字符串	以下值之一，用于指定根据系统验证的配送线路的实际状态：积极非活动加工失败	是的		否
有效状态原因	数组	以下列一个或多个值来指定交付线路有效状态的原因： AdCreativesInactive 验证失败	是的		否
startDatetime	字符串	交付线的开始日期和时间，采用 ISO 8601 格式。如果此值已过去，则无法更改此值。	否		POST、PUT
endDatetime	字符串	传送线的结束日期和时间，采用 ISO 8601 格式。如果此值已过去，则无法更改此值。	否		POST、PUT
createdDatetime	字符串	创建交付线的日期和时间（采用 ISO 8601 格式）。	是的		否
投标类型	字符串	一个值，该值指定交付线的投标类型。目前，唯一支持的值是 CPM。	否	CPM	否
投标金额	十进制	用于投标任何广告请求的投标金额。	否	基于目标市场的平均 CPM 值（此值定期修订）。	否
dailyBudget	十进制	交付线的每日预算。必须设置 dailyBudget 或 lifetimeBudget。	否		POST、PUT（如果未设置 lifetimeBudget）
终身预算	十进制	传输线的生命周期预算。必须设置 lifetimeBudget* 或 dailyBudget。	否		POST，PUT（如果未设置的每日预算）
目标配置文件ID (targetingProfileId)	物体	用于标识目标配置文件的对象，该配置文件描述了您要针对此传送线目标的用户、地理位置和库存类型。此对象由单个 ID 字段组成，该字段指定目标配置文件的 ID。	否		否
创意人员	数组	表示与交付线关联的创意的一个或多个对象。此字段中的每个对象都包含一个 ID 字段，用于指定创意的 ID。	否		否
活动编号	整数	父广告活动的 ID。	否		否
minMinutesPerImp	整数	指定此交付线向同一用户显示的两个印象之间的最小时间间隔（以分钟为单位）。	否	4000	否
进度类型	字符串	指定节奏类型的以下值之一：均匀支出 SpendAsFastAsPossible	否	SpendEvenly	否
货币ID	整数	活动货币的 ID。	是的	开发人员帐户的货币（无需在 POST 或 PUT 调用中指定此字段）	否