Diretrizes de limitação de APIAPI throttling guidance

Aplica-se aApplies to

  • Partner CenterPartner Center

A Microsoft está implementando a limitação da API para permitir um desempenho mais consistente dentro de um período de tempo para parceiros que chamam as APIs do Partner Center.Microsoft is implementing API throttling to allow more consistent performance within a time span for partners calling the Partner Center APIs. A limitação limita o número de solicitações a um serviço em um período de tempo para evitar o uso excessivo de recursos.Throttling limits the number of requests to a service in a time span to prevent overuse of resources. Embora o Partner Center seja projetado para lidar com um alto volume de solicitações, se um número enorme de solicitações ocorrerem por poucos parceiros, a limitação ajuda a manter o desempenho e a confiabilidade ideais para todos os parceiros.While Partner Center is designed to handle a high volume of requests, if an overwhelming number of requests occur by few partners, throttling helps maintain optimal performance and reliability for all partners.

Limites de limitação variam de acordo com o cenário.Throttling limits vary based on the scenario. Por exemplo, se você estiver executando um grande volume de gravação, a possibilidade de limitação será maior do que se você estiver apenas executando leituras.For example, if you are performing a large volume of writes, the possibility for throttling is higher than if you are only performing reads.

O que acontece quando ocorre uma limitação?What happens when throttling occurs?

Quando um limite de limitação é excedido, o Partner Center limita as solicitações adicionais desse cliente por um período de tempo.When a throttling threshold is exceeded, Partner Center limits any further requests from that client for a period of time. O comportamento da limitação depende do tipo e do número de solicitações.Throttling behavior depends on the type and number of requests.

Cenários comuns de limitaçãoCommon throttling scenarios

As causas mais comuns de limitação de clientes incluem:The most common causes of throttling of clients include:

  • Um grande número de solicitações para uma API por ID de locatário de parceiro: para algumas APIs do Partner Center, a limitação é determinada pela ID de locatário do parceiro, muitas chamadas para essas APIs na mesma ID de locatário do parceiro resultarão em exceder o limite de limitação.A large number of requests for an API per Partner Tenant ID: for some Partner Center APIs, throttling is determined by Partner Tenant ID, too many calls to those APIs on the same Partner Tenant ID will result in exceeding the throttling threshold.

  • Um grande número de solicitações para uma API por ID de locatário de parceiro por ID de locatário do cliente: para outras APIs, a limitação é determinada pela combinação de ID de locatário do parceiro/ID de locatário do cliente; nesses casos, fazer muitas chamadas em relação à mesma ID de locatário do cliente resultará em limitação, enquanto as chamadas para outros clientes podem ter sucesso.A large number of requests for an API per Partner Tenant ID per Customer Tenant ID: for other APIs, throttling is determined by Partner Tenant ID/Customer Tenant ID combination; in those cases, making too many calls against the same customer tenant ID will result in throttling - while calls against other customers may succeed.

Práticas recomendadas para evitar a limitaçãoBest practices to avoid throttling

Práticas de programação, como sondagem contínua de um recurso para verificar se há atualizações e examinar regularmente as coleções de recursos para verificar se há recursos novos ou excluídos, são mais prováveis de se levar à limitação e prejudicarão o desempenho geral.Programming practices such as continuously polling a resource to check for updates and regularly scanning resource collections to check for new or deleted resources are more likely to lead to throttling and will degrade overall performance. As chamadas de API simultâneas podem levar a um alto número de solicitações por tempo unitário, o que também fará com que as solicitações sejam limitadas.Concurrent API calls may lead to high number of requests per unit time, which will also cause requests to be throttled. Em vez disso, você deve aproveitar as notificações de alteração e controle de alterações.You should instead leverage change tracking and change notifications. Além disso, você deve ser capaz de aproveitar os logs de atividade para detectar alterações, ver logs de atividade do Partner Center para obter mais informações.Additionally, you should be able to leverage activity logs for detecting changes, see Partner Center activity logs for more information. É altamente recomendável que os parceiros considerem o uso da API do log de atividades para obter mais eficiência e para evitar a limitação.We highly recommend partners to consider using the activity log API for more efficiency and to avoid throttling. Consulte também o exemplo de como usar logs de atividade, abaixo.See also the example of using activity logs, below.

Práticas recomendadas para tratamento de limitaçãoBest practices to handle throttling

Veja a seguir as práticas recomendadas para lidar com a limitação:The following are best practices for handling throttling:

  • Reduza o grau de paralelismo.Reduce the degree of parallelism.
  • Reduzir a frequência de chamadas.Reduce the frequency of calls.
  • Evite repetições imediatas porque todas as solicitações são acumuladas em relação aos limites de uso.Avoid immediate retries because all requests accrue against your usage limits.

Ao implementar o tratamento de erros, use o código de erro HTTP 429 para detectar a limitação.When you implement error handling, use the HTTP error code 429 to detect throttling. A resposta com falha inclui o cabeçalho de resposta Retry-After.The failed response includes the Retry-After response header. O backup de solicitações usando o atraso de nova tentativa é a maneira mais rápida de se recuperar da limitação.Backing off requests using the Retry-after delay is the fastest way to recover from throttling.

Para usar o atraso de tentar novamente, faça o seguinte:To use the Retry-after delay, do the following:

  1. Aguarde o número de segundos especificado no cabeçalho repetir-após.Wait the number of seconds specified in the Retry-After header.

  2. Tente novamente a solicitação.Retry the request.

  3. Se a solicitação falhar novamente com um código de erro 429, você ainda estará sendo limitado.If the request fails again with a 429 error code, you are still being throttled. Tente novamente com retirada exponencial, use o atraso recomendado para tentar novamente e repita a solicitação até obter sucesso.Retry with Exponential backoff, use the recommended Retry-After delay and retry the request until it succeeds.

APIs atualmente afetadas por limitaçãoAPIs currently impacted by throttling

A longo prazo, cada API do centro de parceiros único que chama o ponto de extremidade "api.partnercenter.microsoft.com/" será limitada.In the long run, every single Partner Center API that calls the endpoint “api.partnercenter.microsoft.com/” will be throttled. Atualmente, os limites de limitação são aplicados apenas nas poucas APIs listadas abaixo.Currently, the throttling limits are only enforced on the few APIs listed below. O Partner Center coletará a telemetria em cada uma das APIs e ajustará dinamicamente os limites de limitação.Partner Center will be collecting the telemetry on each of the APIs and will dynamically adjust the throttling limits. A tabela a seguir lista as APIs em que a limitação é imposta no momento.The following table lists the APIs where throttling is currently enforced.

OperaçãoOperation Documentação do Partner CenterPartner Center documentation
{baseURL}/v1/Customers/{customer_id}/Orders{baseURL}/v1/customers/{customer_id}/orders criar um pedidocreate an order
{baseURL}/v1/Customers/{Customer-Tenant-ID}/subscriptions/{ID-for-Subscription}/upgrades{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription}/upgrades transição de uma assinaturatransition a subscription
{baseURL}/v1/Customers/{Customer-Tenant-ID}/Orders/{Order-ID}{baseURL}/v1/customers/{customer-tenant-id}/orders/{order-id} comprar um complemento a uma assinaturapurchase an addon to a subscription
{baseURL}/v1/Customers/{Customer-ID}/carts/{cart-ID}{baseURL}/v1/customers/{customer-id}/carts/{cart-id} criar um carrinhocreate a cart
{baseURL}/v1/Customers/{Customer-ID}/carts/{cart-ID}/checkout{baseURL}/v1/customers/{customer-id}/carts/{cart-id}/checkout fazer checkout de um carrinhocheckout a cart
{baseURL}/v1/Customers/{Customer-ID}/carts/{cart-ID}{baseURL}/v1/customers/{customer-id}/carts/{cart-id} atualizar um carrinhoupdate a cart
{baseURL}/v1/Customers/{Customer-ID}/subscriptions/{Subscription-ID}/registrations{baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/registrations registrar uma assinaturaregister a subscription
{baseURL}/v1/productupgrades{baseURL}/v1/productupgrades criar entidade de atualização de produtocreate product upgrade entity
{baseURL}/v1/Customers/{Customer-ID}/subscriptions/{Subscription-ID}/Conversions{baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/conversions  converter uma assinatura de avaliação em pagaconvert a trial subscription to paid
{baseURL}/v1/Customers/{Customer-Tenant-ID}{baseURL}/v1/customers/{customer-tenant-id} obter um cliente por IDget a customer by id
{baseURL}/v1/productUpgrades/eligibility{baseURL}/v1/productUpgrades/eligibility obter qualificação para a atualização do produtoget eligibility for product upgrade
{baseURL}/v1/Customers/{Customer-Tenant-ID}/subscriptions/{ID-for-Subscription}{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription}  gerenciar assinaturamanage subscription

Resposta do código de erro:Error code response:

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." } 

Exemplo de log de atividadesExample of activity log

Para obter uma prática recomendada na análise de alterações diárias, recomendamos que você consulte o registro de auditoria para um dia específico.For best practice in analyzing daily changes, we recommend that you query audit record for a specific day.

Na resposta, você receberá um resultado com alterações no tipo de operação específico.In the response, you will get a result with changes to specific operation type.Você pode filtrar com base na operação sobre a qual você se preocupa.  You can filter based on the operation you care about. Por exemplo, se você estiver interessado em um cliente recém-criado, poderá examinar OperationType = "add_customer". For example, if you are interested in a newly created customer, you can look at operationType = “add_customer”.

A lista de OperationType/Resources pode ser encontrada nos documentos de API abaixo.List of operationtype/resources can be found in below API docs.

Exemplo de respostaResponse example

Solicitação:Request:

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 

Resposta:Response:   

{ 

    "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" 

    } 

}