パートナーセンター API を呼び出すパートナー向けの API 調整ガイダンス

[アーティクル]
03/05/2024

Microsoft では、パートナーセンター API を呼び出すパートナーに対して、一定の期間内でより一貫性のあるパフォーマンスを実現するために、API 調整を実装しています。リソースの過剰な使用を防ぐため、スロットリングにより、ある期間におけるサービスの要求の数が制限されます。パートナーセンターは大量の要求を処理するように設計されていますが、数社のパートナーから膨大な数の要求が発生した場合、すべてのパートナーに最適なパフォーマンスと信頼性を維持するために調整が役立ちます。

スロットルの制限は、シナリオによって異なります。たとえば、大量の書き込みを実行している場合、読み取りのみを実行する場合よりも調整の可能性が高くなります。

調整が発生した場合はどうなりますか?

調整しきい値を超えた場合、パートナーセンターにより、そのクライアントからのそれ以上の要求が一定期間制限されます。調整動作は、要求の種類と数によって異なります。

スロットルの一般的なシナリオ

クライアントの調整の最も一般的な原因は次のとおりです。

パートナーテナント ID ごとに API に対する多数の要求: 一部のパートナーセンター API の場合、調整はパートナーテナント ID によって決まります。同じパートナーテナント ID でこれらの API に対する呼び出しが多すぎると、スロットルのしきい値を超える結果になります。
顧客テナント ID ごとのパートナーテナント ID ごとの API に対する要求の数が多い:他の API の場合、調整はパートナーテナント ID と顧客テナント ID の組み合わせによって決まります。そのような場合、同じ顧客テナント ID に対して呼び出しが多すぎると調整が発生しますが、他の顧客に対する呼び出しは成功する可能性があります。

調整の回避に関するベストプラクティス

更新プログラムをチェックするためにリソースを継続的にポーリングしたり、リソースコレクションを定期的にスキャンして新しいリソースや削除されたリソースをチェックしたりするなどのプログラミング手法は、調整につながる可能性が高くなり、全体的なパフォーマンスが低下します。 API の同時呼び出しにより、ユニット時間あたりの要求数が多くなる可能性があり、これにより要求が調整される可能性があります。代わりに、変更の追跡と変更の通知を使用する必要があります。さらに、アクティビティログを使用して変更を検出できる必要があります。詳細については、「パートナーセンターのアクティビティログ」を参照してください。効率を高め、調整を回避するために、アクティビティログ API の使用を検討することをパートナーに強くお勧めします。以下のアクティビティログの使用例も参照してください。

スロットル処理のベストプラクティス

調整を処理するためのベストプラクティスを次に示します。

並列処理の次数を減らします。
呼び出しの頻度を減らします。
すべての要求が使用制限に加算されるため、すぐに再試行することは避けてください。

エラー処理を実装するときに、HTTP エラーコード 429 を使用して調整を検出します。失敗した応答には、Retry-After 応答ヘッダーが含まれます。 Retry-After 遅延を使用して要求をバックオフすることが、調整から回復する最も速い方法です。

再試行後の遅延を使用するには:

Retry-After ヘッダーで指定された秒数待ちます。
要求をやり直してください。
要求が 429 エラーコードで再度失敗した場合、引き続き調整されています。指数バックオフで再試行し、推奨される Retry-After 遅延を使用し、成功するまで要求を再試行します。
SDK を使用している場合は、要求が調整されるときに、状態コード 429 で例外が発生します。例外で RetryAfter プロパティを使用し、時間が経過した後に要求を再試行します。

現在調整の影響を受ける API

最終的に、エンドポイント "api.partnercenter.microsoft.com/" を呼び出す 1 つのパートナーセンター API はすべて調整されます。現在、調整の制限は、以下に示す 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}/チェックout	カートをチェックする
{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}	ID で顧客を取得する
{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}	ID でサブスクリプションを取得する
{baseURL}/v1/customers/{customer_id}/orders	顧客のすべての注文を取得する
{baseURL}/v1/customers/{customer_id}/orders/{order_id}	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" を確認できます。

operationtype/resources の一覧については、これらの API ドキュメントを参照してください。

応答の例

要求:

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: de9c2ccc-40dd-4186-9660-65b9b64c3d14 

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": "86bddccf-9a53-40c6-907c-08067a3f8da7", 

            "customerName": "CustomMetersStagingTest", 

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

            "applicationId": "4990cffe-04e8-4e8b-808a-1175604b879f", 

            "resourceType": "order", 

            "resourceNewValue": "{\"Id\":\"Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1\",\"AlternateId\":\"64144d300bde\",\"ReferenceCustomerId\":\"86bddccf-9a53-40c6-907c-08067a3f8da7\",\"BillingCycle\":\"monthly\",\"CurrencyCode\":\"USD\",\"CurrencySymbol\":\"$\",\"LineItems\":[{\"LineItemNumber\":0,\"ProvisioningContext\":null,\"OfferId\":\"DZH318Z0C964:0001:DZH318Z0BZDG\",\"SubscriptionId\":\"f428d44a-d08b-348b-579e-ce92a6362c7b\",\"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/86bddccf-9a53-40c6-907c-08067a3f8da7/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/86bddccf-9a53-40c6-907c-08067a3f8da7/orders/Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]},\"ProvisioningStatus\":{\"Uri\":\"/customers/86bddccf-9a53-40c6-907c-08067a3f8da7/orders/Ia80ZLkXp6eWOqpp35pBQJLhqv9IiGVZ1/provisioningstatus\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]},\"PatchOperation\":{\"Uri\":\"/customers/86bddccf-9a53-40c6-907c-08067a3f8da7/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": "f428d44a-d08b-348b-579e-ce92a6362c7b" 

                }, 

                { 

                    "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": "86bddccf-9a53-40c6-907c-08067a3f8da7", 

            "customerName": "CustomMetersStagingTest", 

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

            "applicationId": "4990cffe-04e8-4e8b-808a-1175604b879f", 

            "resourceType": "customer", 

            "resourceNewValue": "{\"Id\":\"86bddccf-9a53-40c6-907c-08067a3f8da7\",\"CommerceId\":\"9dd78b4f-f98a-44b4-a2fa-2b82ac58d24c\",\"CompanyProfile\":{\"TenantId\":\"86bddccf-9a53-40c6-907c-08067a3f8da7\",\"Domain\":\"CustomMetersStagingTest.onmicrosoft.com\",\"CompanyName\":\"CustomMetersStagingTest\",\"Address\":null,\"Email\":null,\"OrganizationRegistrationNumber\":null,\"Links\":{\"Self\":{\"Uri\":\"/customers/86bddccf-9a53-40c6-907c-08067a3f8da7/profiles/company\",\"Method\":\"GET\",\"Body\":null,\"Headers\":[]}},\"Attributes\":{\"ObjectType\":\"CustomerCompanyProfile\"}},\"BillingProfile\":{\"Id\":\"4beafd7b-cdab-5bdc-52ed-02e16edf2e7a\",\"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" 

    } 

}

パートナーセンター API を呼び出すパートナー向けの API 調整ガイダンス

調整が発生した場合はどうなりますか?

スロットルの一般的なシナリオ

調整の回避に関するベストプラクティス

スロットル処理のベストプラクティス

現在調整の影響を受ける API

エラーコードの応答:

アクティビティログの例

応答の例

フィードバック

フィードバック

その他のリソース

パートナー センター API を呼び出すパートナー向けの API 調整ガイダンス

調整が発生した場合はどうなりますか?

スロットルの一般的なシナリオ

調整の回避に関するベスト プラクティス

スロットル処理のベスト プラクティス

現在調整の影響を受ける API

エラー コードの応答:

アクティビティ ログの例

応答の例

フィードバック

フィードバック

その他のリソース

パートナーセンター API を呼び出すパートナー向けの API 調整ガイダンス

調整の回避に関するベストプラクティス

スロットル処理のベストプラクティス

エラーコードの応答:

アクティビティログの例