Vägledning för API-begränsning för partner som anropar API:er för Partnercenter
Microsoft implementerar API-begränsning för att tillåta mer konsekventa prestanda inom ett tidsintervall för partner som anropar API:erna för Partnercenter. Begränsning begränsar antalet begäranden till en tjänst under ett tidsintervall för att förhindra felaktig användning av resurser. Partnercenter är utformat för att hantera en stor mängd begäranden, men om ett överväldigande antal begäranden inträffar på grund av några få partner, bidrar begränsning till att upprätthålla optimal prestanda och tillförlitlighet för alla partner.
Begränsningsgränserna varierar beroende på scenariot. Om du till exempel utför en stor mängd skrivningar är risken för begränsning högre än om du bara utför läsningar.
Vad händer när begränsningen sker?
När ett tröskelvärde för begränsning överskrids begränsar Partnercenter eventuella ytterligare begäranden från klienten under en tidsperiod. Begränsningsbeteendet beror på typen och antalet begäranden.
Vanliga begränsningsscenarier
De vanligaste orsakerna till begränsning av klienter är:
- Ett stort antal begäranden för ett API per partnerklient-ID: för vissa Partnercenter-API:er bestäms begränsningen av partnerklientorganisations-ID. För många anrop till dessa API:er på samma partnerklient-ID leder till att tröskelvärdet för begränsning överskrids.
- Ett stort antal begäranden för ett API per partnerklient-ID per kundklient-ID: för andra API:er bestäms begränsningen av kombination av partnerklient-ID/kundklient-ID. I dessa fall leder för många anrop mot samma kundklient-ID till begränsning – medan anrop mot andra kunder kan lyckas.
Metodtips för att undvika begränsning
Programmeringsmetoder, till exempel kontinuerlig avsökning av en resurs för att söka efter uppdateringar och regelbundet genomsöka resurssamlingar för att söka efter nya eller borttagna resurser, är mer benägna att leda till begränsning och försämrar övergripande prestanda. Samtidiga API-anrop kan leda till ett stort antal begäranden per enhetstid, vilket gör att begäranden begränsas. Du bör i stället använda ändringsspårning och ändringsmeddelanden. Dessutom bör du kunna använda aktivitetsloggar för att identifiera ändringar. Mer information finns i Aktivitetsloggar för Partnercenter. Vi rekommenderar starkt att partner överväger att använda aktivitetslogg-API:et för mer effektivitet och för att undvika begränsning. Se även exemplet med att använda aktivitetsloggar nedan.
Metodtips för att hantera begränsning
Följande är metodtips för hantering av begränsningar:
- Reducera graden av parallellitet.
- Minska frekvensen för anrop.
- Undvik omedelbara återförsök eftersom alla begäranden ackumuleras mot din användningsförbrukning.
När du implementerar felhantering använder du HTTP-felkoden 429 för att identifiera begränsning. Det misslyckade svaret innehåller svarshuvudet Retry-After. Att avvisa begäranden med hjälp av Retry-After-fördröjning är det snabbaste sättet att återställa från begränsning.
Så här använder du fördröjningen Försök igen:
- Vänta det antal sekunder som anges i återförsökshuvudet.
- Försök igen med begäran.
- Om begäran misslyckas igen med en 429-felkod begränsas du fortfarande. Försök igen med exponentiell rewduktion, använd den rekommenderade återförsöksfördröjningen och försök igen tills den lyckas.
- Om du använder SDK får du ett undantag med statuskod 429 när din begäran begränsas. Använd egenskapen RetryAfter i undantaget och försök igen efter att tiden förflutet.
API:er som för närvarande påverkas av begränsning
Till slut begränsas varje enskilt Partnercenter-API som anropar slutpunkten "api.partnercenter.microsoft.com/". För närvarande tillämpas begränsningsgränserna endast på de API:er som anges nedan. Partnercenter samlar in telemetrin på vart och ett av API:erna och justerar dynamiskt begränsningsgränserna. I följande tabell visas de API:er där begränsning för närvarande tillämpas.
| Åtgärd | Dokumentation för Partnercenter |
|---|---|
| {baseURL}/v1/customers/{customer_id}/orders | skapa en order |
| {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription}/upgrades | övergå till en prenumeration |
| {baseURL}/v1/customers/{customer-tenant-id}/orders/{order-id} | köpa ett tillägg till en prenumeration |
| {baseURL}/v1/customers/{customer-id}/carts/{cart-id} | skapa en kundvagn |
| {baseURL}/v1/customers/{customer-id}/carts/{cart-id}/checkout | checka ut en kundvagn |
| {baseURL}/v1/customers/{customer-id}/carts/{cart-id} | uppdatera en kundvagn |
| {baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/registrations | registrera en prenumeration |
| {baseURL}/v1/productupgrades | skapa entitet för produktuppgradering |
| {baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/conversions | konvertera en utvärderingsprenumeration till betald |
| {baseURL}/v1/customers/{customer-tenant-id} | hämta en kund efter ID |
| {baseURL}/v1/customers/{customer-tenant-id} | ta bort ett kundkonto från sandbox-miljön |
| {baseURL}/v1/customers?size={size} | hämta en lista över kunder |
| {baseURL}/v1/productUpgrades/eligibility | få behörighet för produktuppgradering |
| {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription} | hantera prenumeration |
| {baseURL}/v1/customers/{customer_id}/subscriptions | get-all-of-a-customer-s-subscriptions |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id} | Hämta en prenumeration efter ID |
| {baseURL}/v1/customers/{customer_id}/orders | Hämta alla kundbeställningar |
| {baseURL}/v1/customers/{customer_id}/orders/{order_id} | Hämta en beställning efter ID |
| {baseURL}/v1/customers/{customer_id}/orders/{order_id}/provisioningstatus | Hämta status för prenumerationsetablering |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id} | Hantera beställningar och hantera en prenumeration |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/addons | Hämta en lista över tillägg för en prenumeration |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/azureEntitlements | Hämta en lista över Azure-rättigheter för en prenumeration |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/registrationstatus | Hämta status för prenumerationsregistrering |
| {baseURL}/v1/customers/{customer-tenant-id}/transfers | Hämta alla en kunds överföringar |
| {baseURL}/v1/productUpgrades/{upgrade-id}/status | Hämta status för produktuppgradering |
| {baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/conversions | Hämta en lista över erbjudanden för utvärderingskonvertering |
| {baseURL}/v1/customers/{customer-tenant-id}/migrations/newcommerce/validate | Verifiera en prenumeration för migrering |
| {baseURL}/v1/customers/{customer-tenant-id}/migrations/newcommerce | Skapa en ny köpmigrering |
| {baseURL}/v1/customers/{customerId}/promotionEligibilities | Verifiera en berättigande till befordran |
Felkodssvar:
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." }
Exempel på aktivitetslogg
För bästa praxis vid analys av dagliga ändringar rekommenderar vi att du frågar efter granskningsposter för en viss dag.
I svaret får du ett resultat med ändringar av en viss åtgärdstyp. Du kan filtrera baserat på den åtgärd som du bryr dig om. Om du till exempel är intresserad av en nyskapade kund kan du titta på operationType = "add_customer".
En lista över operationtype/resurser finns i dessa API-dokument.
Svarsexempel
Begäran:
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
Svar:
{
"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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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"
}
}