使用合作夥伴中心 API 來確認客戶接受 Microsoft 客戶合約

發行項
08/02/2024

適用于：合作夥伴中心

不適用 ：由 21Vianet 營運的合作夥伴中心 |美國政府適用的 Microsoft Cloud 合作夥伴中心

合作夥伴中心目前僅支援在「Microsoft 公用雲端」中確認客戶是否接受 Microsoft 客戶合約。

本文說明如何確認或重新確認客戶接受Microsoft 客戶合約。

必要條件

如果您使用合作夥伴中心 .NET SDK，則需要 1.14 版或更新版本。

重要

自 2023 年 6 月起，最新的合作夥伴中心 .NET SDK 3.4.0 版現已封存。您可以從 GitHub 下載 SDK 版本，以及包含實用資訊的讀我檔案。

鼓勵合作夥伴繼續使用合作夥伴中心 REST API 。

認證，如合作夥伴中心驗證所述。此案例僅支援「應用程式 + 使用者」驗證。
客戶識別碼 (customer-tenant-id)。如果您不知道客戶的識別碼，您可以在合作夥伴中心中選取 [客戶 ] 工作區，然後從客戶清單中查看客戶，然後 從 [帳戶 ]。在客戶的 [帳戶] 頁面上，在 [客戶帳戶資訊] 區段中尋找 Microsoft 識別碼 。 Microsoft 識別碼與客戶識別碼 (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();

建立包含確認詳細資料的新合約物件。
使用 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 客戶合約的合約中繼資料。
建立新的合約資源，確認客戶已接受 Microsoft 客戶合約。請使用下列 REST 要求語法。

要求語法

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

URI 參數

使用下列查詢參數來指定您要確認的客戶。

名稱	類型	必填	描述
customer-tenant-id	GUID	Yes	此值是 GUID 格式的 customer-tenant-id，此識別碼可讓您用來指定客戶。

要求標頭

如需詳細資訊，請參閱合作夥伴中心 REST 標頭。

要求本文

下表說明 REST 要求主體中的必要屬性。

名稱	類型	描述
合約	object	合作夥伴提供的詳細資料，用來確認客戶是否接受 Microsoft 客戶合約。

合約

下表說明用來建立合約資源的最低必要欄位數目。

屬性	類型	描述
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": "117a77b0-9360-443b-8795-c6dedc750cf9",
    "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": "117a77b0-9360-443b-8795-c6dedc750cf9",
    "dateAgreed": "2018-06-14T00:00:00.000Z",
    "type": "MicrosoftCustomerAgreement"
}

共用方式為