Delen via

Flexibele toepassingen ontwerpen met Azure Cosmos DB SDK's

  • Artikel

VAN TOEPASSING OP: NoSQL

Bij het ontwerpen van clienttoepassingen die communiceren met Azure Cosmos DB via een van de SDK's, is het belangrijk om een aantal belangrijke basisprincipes te begrijpen. Dit artikel is een ontwerphandleiding voor het begrijpen van deze basisprincipes en het ontwerpen van tolerante toepassingen.

Overzicht

Zie voor een videooverzicht van de concepten die in dit artikel worden besproken:

Connectiviteitsmodi

Azure Cosmos DB SDK's kunnen verbinding maken met de service in twee connectiviteitsmodi. De .NET- en Java-SDK's kunnen verbinding maken met de service in zowel de gateway- als de directe modus, terwijl de anderen alleen verbinding kunnen maken in de gatewaymodus. De gatewaymodus maakt gebruik van het HTTP-protocol en de directe modus maakt doorgaans gebruik van het TCP-protocol.

Gatewaymodus wordt altijd gebruikt om metagegevens op te halen, zoals het account, de container en routeringsgegevens, ongeacht welke modus-SDK is geconfigureerd voor gebruik. Deze informatie wordt in de cache opgeslagen in het geheugen en wordt gebruikt om verbinding te maken met de servicereplica's.

Kortom, voor SDK's in de gatewaymodus kunt u HTTP-verkeer verwachten, terwijl u voor SDK's in de directe modus een combinatie van HTTP- en TCP-verkeer kunt verwachten onder verschillende omstandigheden (zoals initialisatie of het ophalen van metagegevens of routeringsgegevens).

Clientexemplaren en verbindingen

Ongeacht de connectiviteitsmodus is het essentieel om een Singleton-exemplaar van de SDK-client per account per toepassing te onderhouden. Verbindingen, zowel HTTP als TCP, zijn gericht op het clientexemplaren. De meeste rekenomgevingen hebben beperkingen in termen van het aantal verbindingen dat tegelijkertijd kan worden geopend en wanneer deze limieten zijn bereikt, wordt de connectiviteit beïnvloed.

Gedistribueerde toepassingen en netwerken

Wanneer u gedistribueerde toepassingen ontwerpt, zijn er drie belangrijke onderdelen:

  • Uw toepassing en de omgeving waarop deze wordt uitgevoerd.
  • Het netwerk, dat een onderdeel bevat tussen uw toepassing en het Azure Cosmos DB-service-eindpunt.
  • Het Azure Cosmos DB-service-eindpunt.

Wanneer er fouten optreden, vallen ze vaak in een van deze drie gebieden en is het belangrijk om te begrijpen dat het vanwege de gedistribueerde aard van het systeem niet praktisch is om 100% beschikbaarheid voor een van deze onderdelen te verwachten.

Azure Cosmos DB heeft een uitgebreide set beschikbaarheids-SLA's, maar geen van deze is 100%. De netwerkonderdelen die uw toepassing verbinden met het service-eindpunt kunnen tijdelijke hardwareproblemen hebben en pakketten verliezen. Zelfs de rekenomgeving waarin uw toepassing wordt uitgevoerd, kan een CPU-piek hebben die van invloed is op bewerkingen. Deze foutvoorwaarden kunnen van invloed zijn op de bewerkingen van de SDK's en normaal gesproken worden weergegeven als fouten met bepaalde codes.

Uw toepassing moet bestand zijn tegen een bepaalde mate van mogelijke fouten in deze onderdelen door beleid voor opnieuw proberen te implementeren voor de antwoorden van de SDK's.

Moet mijn toepassing opnieuw proberen bij fouten?

Het korte antwoord is ja. Maar niet alle fouten zijn zinvol om het opnieuw te proberen, sommige fout- of statuscodes zijn niet tijdelijk. In de onderstaande tabel worden deze gedetailleerd beschreven:

Statuscode Moet opnieuw proberen toe te voegen SDK's opnieuw proberen Beschrijving
400 Nee Nr. Ongeldige aanvraag
401 Nee Nr. Niet geautoriseerd
403 Optioneel Nee Verboden
404 Nee Nr. Resource is niet gevonden
408 Ja Ja Time-out van aanvraag
409 Nee Nr. Conflictfout is wanneer de identiteit (id en partitiesleutel) die is opgegeven voor een resource voor een schrijfbewerking, is uitgevoerd door een bestaande resource of wanneer een unieke sleutelbeperking is geschonden.
410 Ja Ja Verdwenen uitzonderingen (tijdelijke fout die de SLA niet mag schenden)
412 Nee Nr. Voorwaardefout is de plaats waar de bewerking een eTag heeft opgegeven die verschilt van de versie die beschikbaar is op de server. Dit is een optimistische gelijktijdigheidsfout . Voer de aanvraag opnieuw uit nadat u de meest recente versie van de resource hebt gelezen en de eTag voor de aanvraag hebt bijgewerkt.
413 Nee Nr. Aanvraagentiteit te groot
429 Ja Ja Het is veilig om het opnieuw te proberen op een 429. Raadpleeg de handleiding voor het oplossen van problemen met HTTP 429.
449 Ja Ja Tijdelijke fout die alleen optreedt bij schrijfbewerkingen en veilig is om het opnieuw te proberen. Dit kan wijzen op een ontwerpprobleem waarbij te veel gelijktijdige bewerkingen hetzelfde object proberen bij te werken in Azure Cosmos DB.
500 Nee Nr. De bewerking is mislukt vanwege een onverwachte servicefout. Neem contact op met de ondersteuning door een ondersteuning voor Azure probleem op te geven.
503 Ja Ja Service niet beschikbaar

In de bovenstaande tabel moeten alle statuscodes die zijn gemarkeerd met Ja in de tweede kolom, enige mate van dekking voor nieuwe pogingen in uw toepassing hebben.

HTTP 403

De Sdk's van Azure Cosmos DB proberen niet opnieuw op HTTP 403-fouten in het algemeen, maar er zijn bepaalde fouten gekoppeld aan HTTP 403 waarop uw toepassing kan besluiten te reageren. Als u bijvoorbeeld een foutmelding krijgt die aangeeft dat een partitiesleutel vol is, kunt u besluiten om de partitiesleutel van het document dat u wilt schrijven te wijzigen op basis van een bepaalde bedrijfsregel.

HTTP 429

De Azure Cosmos DB SDK's worden standaard opnieuw geprobeerd op HTTP 429-fouten na de clientconfiguratie en de reactieheader x-ms-retry-after-ms van de service te respecteren door te wachten op de aangegeven tijd en daarna opnieuw te proberen.

Wanneer de SDK-nieuwe pogingen worden overschreden, wordt de fout geretourneerd naar uw toepassing. In het ideale voorbeeld kan het controleren van de x-ms-retry-after-ms header in het antwoord worden gebruikt als hint om te bepalen hoe lang moet worden gewacht voordat de aanvraag opnieuw wordt geprobeerd. Een ander alternatief is een exponentieel back-off-algoritme of het configureren van de client om de nieuwe pogingen op HTTP 429 uit te breiden.

HTTP 449

De Azure Cosmos DB SDK's proberen het opnieuw op HTTP 449 met een incrementele back-off gedurende een bepaalde periode om de meeste scenario's mogelijk te maken.

Wanneer de automatische nieuwe SDK-pogingen worden overschreden, wordt de fout geretourneerd naar uw toepassing. HTTP 449-fouten kunnen veilig opnieuw worden geprobeerd. Vanwege de zeer gelijktijdige aard van schrijfbewerkingen is het beter om een willekeurig uitstelalgoritme te hebben om te voorkomen dat dezelfde mate van gelijktijdigheid na een vast interval wordt herhaald.

Netwerktime-outs en verbindingsfouten behoren tot de meest voorkomende fouten. De Azure Cosmos DB SDK's zijn zelf tolerant en proberen time-outs en verbindingsproblemen in de HTTP- en TCP-protocollen opnieuw als het mogelijk is om het opnieuw te proberen:

  • Voor leesbewerkingen proberen de SDK's een time-out of connectiviteitsfout opnieuw.
  • Voor schrijfbewerkingen worden de SDK's niet opnieuw geprobeerd omdat deze bewerkingen niet idempotent zijn. Wanneer er een time-out optreedt die wacht op het antwoord, is het niet mogelijk om te weten of de aanvraag de service heeft bereikt.

Als het account meerdere regio's beschikbaar heeft, proberen de SDK's ook een nieuwe regio te proberen.

Vanwege de aard van time-outs en connectiviteitsfouten worden deze mogelijk niet weergegeven in de metrische gegevens van uw account, omdat deze alleen betrekking hebben op fouten aan de servicezijde.

Het wordt aanbevolen voor toepassingen om hun eigen beleid voor opnieuw proberen voor deze scenario's te hebben en rekening te houden met het oplossen van schrijftime-outs. Als u bijvoorbeeld een time-out voor maken opnieuw probeert, kan dit een HTTP 409 (conflict) opleveren als de vorige aanvraag de service heeft bereikt, maar het zou lukken als dit niet het gevolg is.

Details van taalspecifieke implementatie

Zie voor meer implementatiedetails met betrekking tot een taal:

Zijn nieuwe pogingen van invloed op mijn latentie?

Vanuit het perspectief van de client zijn nieuwe pogingen van invloed op de end-to-end-latentie van een bewerking. Wanneer de P99-latentie van uw toepassing wordt beïnvloed, is het belangrijk om inzicht te krijgen in de nieuwe pogingen die zich voordoen en hoe u deze kunt aanpakken.

Azure Cosmos DB SDK's bieden gedetailleerde informatie in hun logboeken en diagnostische gegevens waarmee kan worden vastgesteld welke nieuwe pogingen worden uitgevoerd. Zie voor meer informatie hoe u diagnostische gegevens van .NET SDK verzamelt en hoe u Diagnostische gegevens over Java SDK verzamelt.

Hoe kan ik latentie bij opnieuw proberen beperken?

Afhankelijk van de omstandigheden stuurt de SDK in de meeste gevallen aanvragen naar de lokale regio, de schrijfregio (in een scenario met één regio) of de eerste regio in de lijst met voorkeursregio's. Deze prioriteitsaanduiding minimaliseert de latentie in gezonde scenario's door voornamelijk verbinding te maken met het dichtstbijzijnde of meest optimale datacenter.

Deze prioriteitsaanduiding betekent echter ook dat aanvragen die resulteren in een fout altijd eerst in één specifieke regio worden geprobeerd voor een bepaald foutscenario. Als failover naar een andere regio in dat scenario de voorkeur heeft, wordt dit meestal afgehandeld op de infrastructuurlaag (Traffic Manager) in plaats van op SDK-niveau. De juiste installatie en configuratie van uw infrastructuur kunnen ervoor zorgen dat verkeer efficiënt wordt omgeleid tijdens regionale storingen, waardoor de latentie wordt beperkt die kan worden geleverd met nieuwe pogingen in meerdere regio's in een storingsscenario. Raadpleeg de documentatie van Azure Traffic Manager voor meer informatie over het instellen van failover op infrastructuurniveau. Sommige SDK's bieden ondersteuning voor het rechtstreeks implementeren van vergelijkbare failoverstrategieën op SDK-niveau. Zie bijvoorbeeld hoge beschikbaarheid voor Java SDK.

Hoe zit het met regionale storingen?

De Azure Cosmos DB SDK's hebben betrekking op regionale beschikbaarheid en kunnen nieuwe pogingen uitvoeren voor andere accountregio's. Raadpleeg het artikel over scenario's en configuraties voor meerdere regionale omgevingen om te begrijpen welke scenario's betrekking hebben op andere regio's.

Wanneer neemt u contact op met de klantondersteuning

Voer de volgende stappen uit voordat u contact op neemt met de klantondersteuning:

  • Wat is de impact die wordt gemeten qua aantal bewerkingen, vergeleken met het aantal geslaagde bewerkingen? Bevindt deze zich binnen de service-SLA's?
  • Is de P99-latentie beïnvloed?
  • Zijn de fouten gerelateerd aan foutcodes waarop mijn toepassing opnieuw moet proberen en heeft de toepassing betrekking op dergelijke nieuwe pogingen?
  • Zijn de fouten van invloed op al uw toepassingsexemplaren of alleen op een deel ervan? Wanneer het probleem wordt beperkt tot een beperkt aantal exemplaren, betreft het doorgaans een probleem met betrekking tot deze exemplaren.
  • Hebt u de gerelateerde documenten voor probleemoplossing in de bovenstaande tabel doorlopen om een probleem in de toepassingsomgeving uit te sluiten?

Neem contact op met de klantondersteuning als alle toepassingsexemplaren worden beïnvloed of als het percentage betrokken bewerkingen buiten service-SLA's valt of van invloed is op uw eigen sla's voor toepassingen en P99s.

Volgende stappen