使用合作伙伴中心 API 确认客户接受 Microsoft 客户协议

项目
08/02/2024

适用于：合作伙伴中心

不适用于：由世纪互联运营的合作伙伴中心 | Microsoft Cloud for US Government 合作伙伴中心

合作伙伴中心目前仅支持在 Microsoft 公有云中确认客户是否已接受 Microsoft 客户协议。

本文介绍如何确认或重新确认客户是否接受 Microsoft 客户协议。

先决条件

如果使用的是合作伙伴中心 .NET SDK，则需 1.14 或更高版本。

重要

截至 2023 年 6 月，最新的合作伙伴中心 .NET SDK 版本 3.4.0 现已存档。可以从 GitHub 下载 SDK 版本，以及包含有用信息的自述文件。

建议合作伙伴继续使用合作伙伴中心 REST API。

合作伙伴中心身份验证中所述的凭据。此方案仅支持“应用 + 用户”身份验证。
客户 ID (customer-tenant-id)。如果不知道客户的 ID，可以通过选择“客户”工作区，然后从客户列表中选择客户，然后选择“帐户”，在合作伙伴中心中查找该 ID。在客户的“帐户”页上，在“客户帐户信息”部分查找 Microsoft ID。 Microsoft ID 与客户 ID (customer-tenant-id) 相同。
客户接受 Microsoft 客户协议的日期 (dateAgreed)。
客户组织中已接受 Microsoft 客户协议的用户的相关信息。这包括：
- 名字
- 姓氏
- 电子邮件地址
- 电话号码（可选）
如果客户的以下值发生更改，则合作伙伴中心将允许为该客户创建另一个协议：名字，姓氏，电子邮件地址，电话号码。否则，由于创建了重复的客户，合作伙伴将收到以下错误代码

{
"code": 600061,
"message": "A partner confirmed agreement already exists for the customer.",
"description": "A partner confirmed agreement already exists for the customer.",
"errorName": "PartnerConfirmedAgreementAlreadyExists",
"isRetryable": false,
"parameters": {},
"errorMessageExtended": "InternalErrorCode=600061"
}

.NET

若要确认或重新确认客户是否已接受 Microsoft 客户协议，请执行以下操作：

检索 Microsoft 客户协议的协议元数据。必须获取 Microsoft 客户协议的 templateId。有关详细信息，请参阅获取 Microsoft 客户协议的协议元数据。

// IAggregatePartner partnerOperations;

string agreementType = "MicrosoftCustomerAgreement";

var microsoftCustomerAgreementDetails = partnerOperations.AgreementDetails.ByAgreementType(agreementType).Get().Items.Single();

创建新的 Agreement 对象，其中包含确认详细信息。
使用 IAgreggatePartner.Customers 集合，并使用指定的 customer-tenant-id 来调用 ById 方法。

使用 Agreements 属性，随后调用 Create 或 CreateAsync。

// string selectedCustomerId;

var agreementToCreate = new Agreement
{
    DateAgreed = DateTime.UtcNow,
    TemplateId = microsoftCustomerAgreementDetails.TemplateId,
    PrimaryContact = new Contact
    {
        FirstName = "Tania",
        LastName = "Carr",
        Email = "someone@example.com",
        PhoneNumber = "1234567890"
    }
};

Agreement agreement = partnerOperations.Customers.ById(selectedCustomerId).Agreements.Create(agreementToCreate);

可以从控制台测试应用项目的 CreateCustomerAgreement 类中找到完整示例。

REST 请求

若要确认或重新确认客户是否已接受 Microsoft 客户协议，请执行以下操作：

检索 Microsoft 客户协议的协议元数据。必须获取 Microsoft 客户协议的 templateId。有关详细信息，请参阅获取 Microsoft 客户协议的协议元数据。
创建新的 Agreement 资源，确认客户已接受 Microsoft 客户协议。使用以下 REST 请求语法。

请求语法

方法	请求 URI
POST	{baseURL}/v1/customers/{customer-tenant-id}/agreements HTTP/1.1

URI 参数

使用以下查询参数来指定要确认的客户。

名称	Type	需要	说明
customer-tenant-id	GUID	是	该值是 GUID 格式的 customer-tenant-id，是一个用于指定客户的标识符。

请求标头

有关详细信息，请参阅合作伙伴中心 REST 标头。

请求正文

下表说明了 REST 请求正文中的必需属性。

名称	Type	描述
协议	object	合作伙伴提供的详细信息，用于确认客户是否已接受 Microsoft 客户协议。

协议

下表描述了创建协议资源所需的字段（最低要求）。

properties	类型	描述
primaryContact	联系人	客户组织中的已接受 Microsoft 客户协议的用户的相关信息，包括：firstName、lastName、email 和 phoneNumber（可选）
dateAgreed	采用 UTC 日期/时间格式的字符串	客户接受协议的日期。
templateId	string	客户接受的协议类型的唯一标识符。可以通过检索 Microsoft 客户协议的协议元数据来获取 Microsoft 客户协议的 templateId。有关详细信息，请参阅获取 Microsoft 客户协议的协议元数据。
type	string	客户接受的协议类型。如果客户接受了 Microsoft 客户协议，则使用 "MicrosoftCustomerAgreement"。

请求示例

POST https://api.partnercenter.microsoft.com/v1/customers/14876998-c0dc-46e6-9d0c-65a57a6c32ec/agreements HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
MS-RequestId: 94e4e214-6b06-4fb7-96d1-94d559f9b47f
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
{
    "primaryContact": {
        "firstName": "Tania",
        "lastName": "Carr",
        "email": "someone@example.com",
        "phoneNumber": "1234567890"
    },
    "templateId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "dateAgreed": "2018-06-14T00:00:00.000Z",
    "type": "MicrosoftCustomerAgreement"
}

REST 响应

如果成功，此方法会返回一项协议资源。

响应的成功和错误代码

每个响应都带有一个 HTTP 状态代码，用于指示成功或失败以及其他调试信息。

请使用网络跟踪工具来读取此代码、错误类型和其他参数。如需完整列表，请参阅合作伙伴中心 REST 错误代码。

响应示例

HTTP/1.1 201 Created
Content-Length: 261
Content-Type: application/json
MS-RequestId: 94e4e214-6b06-4fb7-96d1-94d559f9b47f
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
{
    "userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "primaryContact": {
        "firstName": "Tania",
        "lastName": "Carr",
        "email": "someone@example.com",
        "phoneNumber": "1234567890"
    },
    "templateId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "dateAgreed": "2018-06-14T00:00:00.000Z",
    "type": "MicrosoftCustomerAgreement"
}

通过