Richtlijnen voor API-beperking voor partners die Partner Center-API's aanroepen
Microsoft implementeert API-beperking om binnen een bepaalde periode consistentere prestaties mogelijk te maken voor partners die de Partner Center-API's aanroepen. Het aantal aanvragen naar een service in een tijdsduur wordt beperkt om te voorkomen dat bronnen overmatig worden gebruikt. Hoewel partnercentrum is ontworpen om een groot aantal aanvragen af te handelen, helpt beperking om optimale prestaties en betrouwbaarheid voor alle partners te behouden als er een overweldigend aantal aanvragen voorkomt door slechts enkele partners.
Beperkingslimieten variëren op basis van het scenario. Als u bijvoorbeeld een groot aantal schrijfbewerkingen uitvoert, is de mogelijkheid voor beperking hoger dan als u alleen leesbewerkingen uitvoert.
Wat gebeurt er wanneer beperking plaatsvindt?
Wanneer een beperkingsdrempel wordt overschreden, beperkt Het Partnercentrum eventuele verdere aanvragen van die client gedurende een bepaalde periode. Het beperkingsgedrag is afhankelijk van het type en het aantal aanvragen.
Gebruikelijke beperkingsscenario's
De meest voorkomende oorzaken van beperking van clients zijn:
- Een groot aantal aanvragen voor een API per partnertenant-id: voor sommige Partnercentrum-API's wordt beperking bepaald door de tenant-id van de partner. Te veel aanroepen naar deze API's op dezelfde partnertenant-id leiden ertoe dat de drempelwaarde voor beperking wordt overschreden.
- Een groot aantal aanvragen voor een API per partnertenant-id per tenant-id van de klant: voor andere API's wordt beperking bepaald door combinatie van tenant-id/klanttenant-id van de partner. In die gevallen leidt het maken van te veel aanroepen op basis van dezelfde tenant-id van de klant tot beperking, terwijl aanroepen voor andere klanten kunnen slagen.
Best practices om aanvraagbeperking te voorkomen
Programmeerprocedures, zoals het continu peilen van een resource om te controleren op updates en het regelmatig scannen van resourceverzamelingen om te controleren op nieuwe of verwijderde resources, leiden waarschijnlijker tot beperking en verminderde algehele prestaties. Gelijktijdige API-aanroepen kunnen leiden tot een groot aantal aanvragen per eenheidstijd, waardoor aanvragen worden beperkt. Gebruik in plaats daarvan wijzigingen bijhouden en wijzigingsmeldingen. Daarnaast moet u activiteitenlogboeken kunnen gebruiken voor het detecteren van wijzigingen. Zie activiteitenlogboeken van Partnercentrum voor meer informatie. We raden partners ten zeerste aan om de API voor activiteitenlogboeken te gebruiken voor meer efficiëntie en om beperking te voorkomen. Zie ook het voorbeeld van het gebruik van activiteitenlogboeken hieronder.
Best practices voor het verwerken van aanvraagbeperking
Hier volgen de aanbevolen procedures voor het afhandelen van beperking:
- Verminder te gebruiken niveau van parallelle uitvoering.
- Verminder de frequentie van aanroepen.
- Vermijd onmiddellijke nieuwe pogingen omdat alle aanvragen worden opgebouwd op basis van uw gebruikslimieten.
Gebruik de HTTP-foutcode 429 om beperking te detecteren wanneer u foutafhandeling implementeert. De mislukte reactie bevat de antwoordheader Retry-After. Het uitstellen van aanvragen met behulp van de vertraging Retry-After is de snelste manier om te herstellen van beperking.
De vertraging opnieuw proberen gebruiken:
- Wacht het aantal seconden dat is gespecificeerd in de header Retry-After.
- Probeer de aanvraag opnieuw.
- Als de aanvraag opnieuw mislukt met een 429-foutcode, krijgt u nog steeds met beperkingen te maken. Probeer het opnieuw met Exponentieel uitstel, gebruik de aanbevolen vertraging na opnieuw proberen en voer de aanvraag opnieuw uit totdat deze is geslaagd.
- Als u de SDK gebruikt, ontvangt u een uitzondering met statuscode 429 wanneer uw aanvraag wordt beperkt. Gebruik de eigenschap RetryAfter in de uitzondering en voer de aanvraag opnieuw uit nadat de tijd is verstreken.
API's die momenteel worden beïnvloed door beperking
Uiteindelijk wordt elke API van partnercentrum die het eindpunt 'api.partnercenter.microsoft.com/' aanroept, beperkt. Momenteel worden de beperkingslimieten alleen afgedwongen op de onderstaande API's. Partner Center verzamelt de telemetrie op elk van de API's en past de beperkingslimieten dynamisch aan. De volgende tabel bevat de API's waarbij beperking momenteel wordt afgedwongen.
| Bewerking | Documentatie voor Partnercentrum |
|---|---|
| {baseURL}/v1/customers/{customer_id}/orders | een bestelling maken |
| {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription}/upgrades | een abonnement overdragen |
| {baseURL}/v1/customers/{customer-tenant-id}/orders/{order-id} | een invoegtoepassing kopen voor een abonnement |
| {baseURL}/v1/customers/{customer-id}/carts/{cart-id} | een winkelwagen maken |
| {baseURL}/v1/customers/{customer-id}/carts/{cart-id}/checkout | een winkelwagen uitchecken |
| {baseURL}/v1/customers/{customer-id}/carts/{cart-id} | een winkelwagen bijwerken |
| {baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/registrations | een abonnement registreren |
| {baseURL}/v1/productupgrades | een entiteit voor productupgrade maken |
| {baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/conversions | een proefabonnement converteren naar betaald |
| {baseURL}/v1/customers/{customer-tenant-id} | een klant ophalen op basis van id |
| {baseURL}/v1/customers?size={size} | een lijst met klanten ophalen |
| {baseURL}/v1/productUpgrades/geschiktheid | geschiktheid krijgen voor productupgrade |
| {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription} | abonnement beheren |
| {baseURL}/v1/customers/{customer_id}/subscriptions | get-all-of-a-customer-s-subscriptions |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id} | Een abonnement ophalen op id |
| {baseURL}/v1/customers/{customer_id}/orders | Alle klantorders ophalen |
| {baseURL}/v1/customers/{customer_id}/orders/{order_id} | Een order ophalen op id |
| {baseURL}/v1/customers/{customer_id}/orders/{order_id}/provisioningstatus | Inrichtingsstatus van abonnement ophalen |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id} | Orders beheren en een abonnement beheren |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/addons | Een lijst met invoegtoepassingen voor een abonnement ophalen |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/azureEntitlements | Een lijst met Azure-rechten voor een abonnement ophalen |
| {baseURL}/v1/customers/{customer_id}/subscriptions/{subscription_id}/registrationstatus | Registratiestatus van abonnement ophalen |
| {baseURL}/v1/customers/{customer-tenant-id}/transfers | Alle overdrachten van een klant ophalen |
| {baseURL}/v1/productUpgrades/{upgrade-id}/status | Status van productupgrade ophalen |
| {baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/conversions | Een lijst met aanbiedingen voor proefconversie ophalen |
| {baseURL}/v1/customers/{customer-tenant-id}/migrations/newcommerce/validate | Een abonnement valideren voor migratie |
| {baseURL}/v1/customers/{customer-tenant-id}/migrations/newcommerce | Een nieuwe commerce-migratie maken |
| {baseURL}/v1/customers/{customerId}/promotionEligibilities | Een promotie-geschiktheid controleren |
Antwoord op foutcode:
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." }
Voorbeeld van activiteitenlogboek
Voor aanbevolen procedures bij het analyseren van dagelijkse wijzigingen raden we u aan om een query uit te voeren op de auditrecord voor een specifieke dag.
In het antwoord krijgt u een resultaat met wijzigingen in het specifieke bewerkingstype. U kunt filteren op basis van de bewerking die u belangrijk vindt. Als u bijvoorbeeld geïnteresseerd bent in een nieuwe klant, kunt u operationType = "add_customer" bekijken.
De lijst met operationtype/resources vindt u in deze API-documenten.
Responsvoorbeeld
Aanvraag:
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
Antwoord:
{
"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"
}
}