對於合作夥伴呼叫合作夥伴中心 API 的 API 節流指引

文章
11/05/2024

Microsoft正在實作 API 節流，以允許合作夥伴呼叫合作夥伴中心 API 的時間範圍內更一致的效能。節流會限制在某個時間範圍內對服務的要求數目，以避免過度使用資源。雖然合作夥伴中心依設計可處理大量要求，但若有幾個合作夥伴提出了極大量的要求，節流有助於為所有合作夥伴維持理想的效能和可靠性。

節流限制視情節而異。例如，如果您正在執行大量的寫入，節流的可能性會高於您只執行讀取的可能性。

節流發生時會發生什麼事？

超過節流閾值時，合作夥伴中心會限制來自該用戶端的任何進一步要求一段時間。節流行為取決於要求類型和數目。

常見的節流案例

用戶端節流最常見的原因包括：

每個合作夥伴租使用者標識碼 API 的大量要求：對於某些合作夥伴中心 API，節流是由合作夥伴租使用者標識碼所決定。對相同合作夥伴租使用者標識碼上這些 API 的呼叫太多會導致超過節流閾值。
每個合作夥伴租使用者標識碼每個合作夥伴租使用者標識符的 API 大量要求：針對其他 API，節流是由合作夥伴租使用者標識碼/客戶租使用者標識符組合所決定;在這些情況下，對相同客戶租使用者標識符進行太多呼叫會導致節流 - 而對其他客戶的呼叫可能會成功。

避免節流的最佳做法

程序設計做法，例如持續輪詢資源以檢查更新，並定期掃描資源集合以檢查新的或刪除的資源，更可能導致節流和降低整體效能。並行 API 呼叫可能會導致每個單位時間的要求數目很高，這會導致要求受到節流。您應該改用變更追蹤和變更通知。此外，您應該能夠使用活動記錄來偵測變更。如需詳細資訊，請參閱合作夥伴中心活動記錄。強烈建議合作夥伴考慮使用活動記錄 API 以提高效率，並避免節流。另請參閱以下使用活動記錄的範例。

處理節流的最佳做法

以下是處理節流的最佳作法：

減少平行處理原則的程度。
減少通話的頻率。
避免立即做出重試，因為所有的要求都會納入使用量限制的計算。

實作錯誤處理時，請使用 HTTP 錯誤碼 429 來偵測用戶端節流。失敗的回應包括「稍候再試」回應標頭。使用重試後延遲來備份要求是從節流復原的最快方式。

若要使用重試後的延遲：

等候「稍候再試」標頭中指定的秒數。
重試要求。
如果要求再次失敗，錯誤碼為 429，表示您仍受到節流。透過指數輪詢重試，請使用建議的「稍候再試」延遲，然後重試要求，直到要求成功為止。
如果您使用 SDK，當您的要求被節流時，會收到狀態代碼為 429 的例外狀況。在例外狀況中使用「稍候再試」屬性，並在經過該時間之後重試要求。

目前受節流影響的 API

最後，每個呼叫端點的合作夥伴中心 API 都會受到節流處理，「api.partnercenter.microsoft.com/」。目前，節流限制只會在下列 API 上強制執行。合作夥伴中心會收集每個 API 上的遙測數據，並動態調整節流限制。下表列出目前強制執行節流的 API。

運算	合作夥伴中心文件
{baseURL}/v1/customers/{customer_id}/orders	建立訂單
{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription}/upgrades	轉換訂用帳戶
{baseURL}/v1/customers/{customer-tenant-id}/orders/{order-id}	購買訂用帳戶的附加元件
{baseURL}/v1/customers/{customer-id}/carts/{cart-id}	建立購物車
{baseURL}/v1/customers/{customer-id}/carts/{cart-id}/checkout	結帳購物車
{baseURL}/v1/customers/{customer-id}/carts/{cart-id}	更新購物車
{baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/registrations	註冊訂用帳戶
{baseURL}/v1/productupgrades	建立產品升級實體
{baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/conversions	將試用版訂用帳戶轉換為付費
{baseURL}/v1/customers/{customer-tenant-id}	依標識碼取得客戶
{baseURL}/v1/customers？size={size}	取得客戶清單
{baseURL}/v1/productUpgrades/eligibility	取得產品升級的資格
{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription}	管理訂用帳戶
{baseURL}/v1/customers/{customer_id}/subscriptions	get-all-of-a-customer-s-subscriptions
{baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}	依照識別碼取得訂用帳戶
{baseURL}/v1/customers/{customer_id}/orders	取得所有客戶訂單
{baseURL}/v1/customers/{customer_id}/orders/{order_id}	依識別碼取得供應項目
{baseURL}/v1/customers/{customer_id}/orders/{order_id}/provisioningstatus	取得訂用帳戶的佈建狀態
{baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}	管理訂單和管理訂用帳戶
{baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/addons	取得訂用帳戶的附加元件清單
{baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/azureEntitlements	取得訂用帳戶的 Azure 權利清單
{baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/registrationstatus	取得訂用帳戶的註冊狀態
{baseURL}/v1/customers/{customer-tenant-id}/transfers	取得客戶的所有轉移
{baseURL}/v1/productUpgrades/{upgrade-id}/status	取得產品升級狀態
{baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/conversions	取得試用版轉換方案的清單
{baseURL}/v1/customers/{customer-tenant-id}/migrations/newcommerce/validate	驗證訂用帳戶以便移轉
{baseURL}/v1/customers/{customer-tenant-id}/migrations/newcommerce	建立新的商務移轉
{baseURL}/v1/customers/{customerId}/promotionEligibilities	確認促銷資格

錯誤碼回應：

HTTP/1.1 429 Too Many Requests 

Content-Length: 84 

Content-Type: application/json 

Retry-After: 57 

Date: Tue, 21 Jul 2020 04:10:58 GMT 

{ "statusCode": 429, "message": "Rate limit is exceeded. Try again in 57 seconds." }

活動記錄的範例

如需分析每日變更的最佳做法，建議您查詢特定日期的稽核記錄。

在回應中，您會取得具有特定作業類型變更的結果。您可以根據您關心的作業進行篩選。例如，如果您對新建立的客戶感興趣，您可以查看 operationType = “add_customer”。

您可以在這些 API 檔中找到 operationtype/resources 清單。

回應範例

要求：

Http Get call: https://api.partnercenter.microsoft.com/v1/auditrecords?startDate=2020-09-02&endDate=2020-09-02&size=50 

Authorization: Bearer <token> 

Accept: application/json 

MS-RequestId: 127facaa-e389-41f8-8bb7-1d1af99db893 

MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd 

X-Locale: en-US 

Host: api.partnercenter.microsoft.com 

Connection: Keep-Alive

回應：

{ 

    "totalCount": 17, 

    "items": [ 

        { 

            "id": "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d_e905b566-4779-4e57-944c-7b1b5312705b_updatecustomeruserlicenses_637346859797753934", 

            "partnerId": "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d", 

            "participants": [ 

                "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d" 

            ], 

            "customerId": "e905b566-4779-4e57-944c-7b1b5312705b", 

            "userPrincipalName": "admin@testsw09.onmicrosoft.com", 

            "applicationId": "FulfillmentService", 

            "resourceType": "license", 

            "operationType": "update_customer_user_licenses", 

            "operationDate": "2020-09-02T23:26:19.7753934Z", 

            "operationStatus": "succeeded", 

            "customizedData": [ 

                { 

                    "key": "CustomerUserId", 

                    "value": "933808c7-b165-496c-a24e-1a4b7846fab4" 

                } 

            ], 

            "attributes": { 

                "objectType": "AuditRecord" 

            } 

        }, 

        { 

            "id": "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d_86bddccf-9a53-40c6-907c-08067a3f8da7_ia80zlkxp6ewoqpp35pbqjlhqv9iigvz1_createorder_637346662909268372", 

            "partnerId": "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d", 

            "participants": [ 

                "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d" 

            ], 

            "customerId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", 

            "customerName": "CustomMetersStagingTest", 

            "userPrincipalName": "admin@testsw09.onmicrosoft.com", 

            "applicationId": "00001111-aaaa-2222-bbbb-3333cccc4444", 

            "resourceType": "order", 

            "resourceNewValue": "{\"Id\":\"Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1\",\"AlternateId\":\"64144d300bde\",\"ReferenceCustomerId\":\"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\"BillingCycle\":\"monthly\",\"CurrencyCode\":\"USD\",\"CurrencySymbol\":\"$\",\"LineItems\":[{\"LineItemNumber\":0,\"ProvisioningContext\":null,\"OfferId\":\"DZH318Z0C964:0001:DZH318Z0BZDG\",\"SubscriptionId\":\"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e\",\"ParentSubscriptionId\":null,\"TermDuration\":\"P1M\",\"TransactionType\":\"New\",\"FriendlyName\":\"SaaS custom meter offer - Bronze\",\"Quantity\":1,\"Pricing\":null,\"PartnerIdOnRecord\":null,\"RenewsTo\":null,\"Links\":{\"Product\":{\"Uri\":\"/products/DZH318Z0C964?country=US\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]},\"Sku\":{\"Uri\":\"/products/DZH318Z0C964/skus/0001?country=US\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]},\"Availability\":{\"Uri\":\"/products/DZH318Z0C964/skus/0001/availabilities/DZH318Z0BZDG?country=US\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]},\"ActivationLinks\":{\"Uri\":\"/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/orders/Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1/lineitems/0/activationlinks\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]}}}],\"CreationDate\":\"2020-09-02T17:58:01.7755853Z\",\"Status\":\"pending\",\"TransactionType\":\"UserPurchase\",\"Links\":{\"Self\":{\"Uri\":\"/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/orders/Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]},\"ProvisioningStatus\":{\"Uri\":\"/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/orders/Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1/provisioningstatus\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]},\"PatchOperation\":{\"Uri\":\"/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/orders/Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1\",\"Method\":\"PATCH\",\"Body\":null,\"Headers\":[]}},\"Client\":{\"marketplaceCountry\":\"US\",\"deviceFamily\":\"UniversalStore-PartnerCenter\",\"name\":\"Partner Center Web\"},\"Attributes\":{\"ObjectType\":\"Order\"}}", 

            "operationType": "create_order", 

            "originalCorrelationId": "96514ebe-c1b2-4865-cb46-2c2d20a2e911", 

            "operationDate": "2020-09-02T17:58:10.9268372Z", 

            "operationStatus": "succeeded", 

            "customizedData": [ 

                { 

                    "key": "OrderId", 

                    "value": "Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1" 

                }, 

                { 

                    "key": "AlternateId", 

                    "value": "64144d300bde" 

                }, 

                { 

                    "key": "BillingCycle", 

                    "value": "Monthly" 

                }, 

                { 

                    "key": "OfferId-0", 

                    "value": "DZH318Z0C964:0001:DZH318Z0BZDG" 

                }, 

                { 

                    "key": "SubscriptionId-0", 

                    "value": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e" 

                }, 

                { 

                    "key": "SubscriptionName-0", 

                    "value": "SaaS custom meter offer - Bronze" 

                }, 

                { 

                   "key": "Quantity-0", 

                    "value": "1" 

                }, 

                { 

                    "key": "PartnerOnRecord-0", 

                    "value": null 

                } 

            ], 

            "attributes": { 

                "objectType": "AuditRecord" 

            } 

        }, 

                           { 

            "id": "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d_86bddccf-9a53-40c6-907c-08067a3f8da7_86bddccf-9a53-40c6-907c-08067a3f8da7_addcustomer_637346648528069005", 

            "partnerId": "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d", 

            "participants": [ 

                "9daaeb1c-4195-4db5-9f1d-509eb70c8c2d" 

            ], 

            "customerId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", 

            "customerName": "CustomMetersStagingTest", 

            "userPrincipalName": "admin@testsw09.onmicrosoft.com", 

            "applicationId": "00001111-aaaa-2222-bbbb-3333cccc4444", 

            "resourceType": "customer", 

            "resourceNewValue": "{\"Id\":\"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\"CommerceId\":\"9dd78b4f-f98a-44b4-a2fa-2b82ac58d24c\",\"CompanyProfile\":{\"TenantId\":\"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\"Domain\":\"CustomMetersStagingTest.onmicrosoft.com\",\"CompanyName\":\"CustomMetersStagingTest\",\"Address\":null,\"Email\":null,\"OrganizationRegistrationNumber\":null,\"Links\":{\"Self\":{\"Uri\":\"/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/profiles/company\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]}},\"Attributes\":{\"ObjectType\":\"CustomerCompanyProfile\"}},\"BillingProfile\":{\"Id\":\"bbbbcccc-1111-dddd-2222-eeee3333ffff\",\"FirstName\":\"CustomMetersStagingTest\",\"LastName\":\"CustomMetersStagingTest\",\"Email\":\"CustomMetersStagingTest@CustomMetersStagingTest.com\",\"Culture\":\"en-US\",\"Language\":\"en\",\"CompanyName\":\"CustomMetersStagingTest\",\"DefaultAddress\":{\"Id\":null,\"Country\":\"US\",\"Region\":null,\"City\":\"Seattle\",\"State\":\"WA\",\"District\":null,\"AddressLine1\":\"CustomMetersStagingTest\",\"AddressLine2\":null,\"AddressLine3\":null,\"PostalCode\":\"98122\",\"FirstName\":\"CustomMetersStagingTest\",\"LastName\":\"CustomMetersStagingTest\",\"EmailAddress\":null,\"PhoneNumber\":null,\"MiddleName\":null},\"Attributes\":{\"Etag\":\"-2279334701316321663\",\"ObjectType\":\"CustomerBillingProfile\"}},\"RelationshipToPartner\":\"reseller\",\"AllowDelegatedAccess\":true,\"UserCredentials\":{\"userName\":\"admin\",\"password\":\"\"},\"AssociatedPartnerId\":null,\"CustomDomains\":null,\"Attributes\":{\"ObjectType\":\"Customer\"}}", 

            "operationType": "add_customer", 

            "originalCorrelationId": "7550d9ea-e64a-416f-e49b-3670c516cf69", 

            "operationDate": "2020-09-02T17:34:12.8069005Z", 

            "operationStatus": "succeeded", 

            "customizedData": [ 

                { 

                    "key": "PrimaryDomainName", 

                    "value": "CustomMetersStagingTest.onmicrosoft.com" 

                }, 

                { 

                    "key": "Relationship", 

                    "value": "Reseller" 

                } 

            ], 

            "attributes": { 

                "objectType": "AuditRecord" 

            } 

        }, 

                            

        ... 

    ], 

    "links": { 

        "self": { 

            "uri": "/auditrecords?startDate=2020-09-02&endDate=2020-09-02&size=50", 

            "method": "GET", 

            "headers": [] 

        } 

    }, 

    "attributes": { 

        "objectType": "Collection" 

    } 

}

分享方式：