Problemen met de Azure Functions-trigger voor Azure Cosmos DB for NoSQL vaststellen en oplossen

Artikel
09/28/2024

VAN TOEPASSING OP: NoSQL

In dit artikel worden veelvoorkomende problemen, tijdelijke oplossingen en diagnostische stappen beschreven wanneer u de Azure Functions-trigger gebruikt voor Azure Cosmos DB voor NoSQL.

Afhankelijkheden

De triggers en bindingen van Azure Functions voor Azure Cosmos DB for NoSQL zijn afhankelijk van het extensiepakket Microsoft.Azure.WebJobs.Extensions.CosmosDB via de Azure Functions-basisruntime. Bewaar deze pakketten altijd bijgewerkt, omdat ze oplossingen en nieuwe functies bevatten waarmee u potentiële problemen kunt oplossen die u kunt tegenkomen.

De Azure Cosmos DB SDK onafhankelijk gebruiken

De belangrijkste functionaliteit van het extensiepakket is om ondersteuning te bieden voor de Azure Functions-triggers en -bindingen voor Azure Cosmos DB. Het pakket bevat ook de Azure Cosmos DB .NET SDK, wat handig is als u programmatisch wilt communiceren met Azure Cosmos DB zonder de trigger en bindingen te gebruiken.

Als u de Azure Cosmos DB SDK wilt gebruiken, moet u ervoor zorgen dat u geen verwijzing naar een ander NuGet-pakket toevoegt aan uw project. Laat in plaats daarvan de SDK-verwijzing oplossen via het Azure Functions-extensiepakket. Gebruik de Azure Cosmos DB SDK afzonderlijk van de trigger en bindingen.

Als u handmatig uw eigen exemplaar van de Azure Cosmos DB SDK-client maakt, moet u bovendien het patroon volgen van slechts één exemplaar van de client en een singleton-patroonbenadering gebruiken. Dit proces voorkomt mogelijke socketproblemen in uw bewerkingen.

Algemene scenario's en tijdelijke oplossingen

Uw Azure-functie mislukt met een foutbericht dat de verzameling '`doesn't exist`'

De Azure-functie mislukt met het volgende foutbericht: 'De bronverzameling collection-name (in database database-name) of de leaseverzameling collection2-name (in database database2-name) bestaat niet. Beide verzamelingen moeten bestaan voordat de listener wordt gestart. Als u de leaseverzameling automatisch wilt maken, stelt u deze in op CreateLeaseCollectionIfNotExists true.

Deze fout betekent dat een of beide Azure Cosmos DB-containers die vereist zijn om de trigger te laten werken:

Niet bestaan
Zijn niet bereikbaar voor de Azure-functie

De fouttekst zelf geeft aan welke Azure Cosmos DB-database en -container de trigger zoekt, op basis van uw configuratie.

Ga als volgt te werk om het probleem op te lossen:

Controleer het Connection kenmerk en of deze verwijst naar een instelling die bestaat in uw Azure-functie-app.
- De waarde voor dit kenmerk mag niet de verbindingsreeks zelf zijn, maar de naam van de configuratie-instelling.
Controleer of de databaseName en containerName waarden aanwezig zijn in uw Azure Cosmos DB-account.
- Als u automatische vervanging van waarden (met behulp van %settingName% patronen) gebruikt, moet u ervoor zorgen dat de naam van de instelling bestaat in uw Azure-functie-app.
Als u geen waarde opgeeft LeaseContainerName/leaseContainerName , is de standaardwaarde leases. Controleer of een dergelijke container bestaat.
- U kunt het kenmerk in de CreateLeaseContainerIfNotExists trigger true desgewenst zo instellen dat het automatisch wordt gemaakt.
Om ervoor te zorgen dat uw Azure Cosmos DB-account de Azure-functie niet blokkeert, controleert u de firewallconfiguratie van uw Azure Cosmos DB-account.

Uw Azure-functie kan niet worden gestart, met het foutbericht '`Shared throughput collection should have a partition key`'

Eerdere versies van de Azure Cosmos DB-extensie bieden geen ondersteuning voor het gebruik van een leasecontainer die is gemaakt in een gedeelde doorvoerdatabase.

Ga als volgt te werk om het probleem op te lossen:

Werk de extensie Microsoft.Azure.WebJobs.Extensions.CosmosDB bij om de nieuwste versie op te halen.

Uw Azure-functie kan niet worden gestart, met het foutbericht '`PartitionKey must be supplied for this operation`'

Deze fout betekent dat u momenteel een gepartitioneerde leaseverzameling gebruikt met een oude uitbreidingsafhankelijkheid.

Ga als volgt te werk om het probleem op te lossen:

Voer een upgrade uit naar de nieuwste beschikbare versie.

Uw Azure-functie kan niet worden gestart, met het foutbericht '`Forbidden (403); Substatus: 5300... The given request [POST ...] can't be authorized by Microsoft Entra token in data plane`'

Deze fout betekent dat uw functie een niet-gegevensbewerking probeert uit te voeren met Microsoft Entra-identiteiten. U kunt CreateLeaseContainerIfNotExists = true niet gebruiken wanneer u Microsoft Entra-identiteiten gebruikt.

Uw Azure-functie kan niet worden gestart, met het foutbericht '`The lease collection, if partitioned, must have partition key equal to id`'

Deze fout betekent dat uw huidige leasecontainer is gepartitioneerd, maar het pad naar de partitiesleutel niet /id.

Ga als volgt te werk om het probleem op te lossen:

Maak de leasecontainer opnieuw met /id als partitiesleutel.

Wanneer u de trigger probeert uit te voeren, krijgt u het foutbericht '`Value can't be null. Parameter name: o" in your Azure function logs`'

Dit probleem kan zich voordoen als u Azure Portal gebruikt en u de knop Uitvoeren selecteert wanneer u een Azure-functie inspecteert die gebruikmaakt van de trigger. Voor de trigger hoeft u Uitvoeren niet te selecteren om deze te starten. Deze wordt automatisch gestart wanneer u de functie implementeert.

Ga als volgt te werk om het probleem op te lossen:

Als u de logboekstream van de functie in Azure Portal wilt controleren, gaat u naar de bewaakte container en voegt u enkele nieuwe items in. De trigger wordt automatisch uitgevoerd.

Het duurt te lang om uw wijzigingen te ontvangen

Dit scenario kan meerdere oorzaken hebben. Overweeg een of meer van de volgende oplossingen uit te proberen:

Worden uw Azure-functie en uw Azure Cosmos DB-account geïmplementeerd in afzonderlijke regio's? Voor optimale netwerklatentie moeten uw Azure-functie en uw Azure Cosmos DB-account zich in dezelfde Azure-regio bevinden.
Zijn de wijzigingen die zich voordoen in uw Azure Cosmos DB-container doorlopend of sporadisch?
- Als ze sporadisch zijn, kan er enige vertraging optreden tussen de wijzigingen die worden opgeslagen en de Azure-functie die ze ophaalt. Dit gedrag treedt op wanneer de trigger intern controleert op wijzigingen in uw Azure Cosmos DB-container en geen wijzigingen vindt die wachten om te worden gelezen. De trigger slaapt vervolgens gedurende een configureerbare hoeveelheid tijd (standaard 5 seconden) voordat er wordt gecontroleerd op nieuwe wijzigingen. De trigger maakt gebruik van dit gedrag om een hoog RU-verbruik (request unit) te voorkomen. U kunt de slaapstand configureren via de FeedPollDelay/feedPollDelay instelling in de configuratie van uw trigger. De waarde is naar verwachting in milliseconden.
Voor uw Azure Cosmos DB-container kunnen snelheidsbeperkingen gelden.
U kunt het PreferredLocations kenmerk in uw trigger gebruiken om een door komma's gescheiden lijst met Azure-regio's op te geven om een aangepaste verbindingsvolgorde van voorkeur te definiëren.
De snelheid waarmee u nieuwe wijzigingen verwerkt, bepaalt de snelheid waarmee uw trigger deze wijzigingen ontvangt. Controleer de uitvoeringstijd of duur van de functie. Als uw functie traag is, neemt dat de tijd die nodig is voordat de trigger nieuwe wijzigingen krijgt, toe. Als u een recente toename van de duur ziet, kan dit van invloed zijn op een recente codewijziging. Als de snelheid waarmee u bewerkingen ontvangt in uw Azure Cosmos DB-container sneller is dan de snelheid van uw trigger, blijft deze achter. U kunt de code van de functie onderzoeken om de meest tijdrovende bewerking te bepalen en hoe u deze kunt optimaliseren.
U kunt logboeken voor foutopsporing gebruiken om de diagnostische gegevens te controleren en te controleren of er netwerkvertragingen zijn.

Sommige wijzigingen worden herhaald in mijn trigger

Het concept van een wijziging is een bewerking voor een item. De meest voorkomende scenario's waarin gebeurtenissen voor hetzelfde item worden ontvangen, zijn:

Uw functie mislukt tijdens de uitvoering. Als beleid voor opnieuw proberen is ingeschakeld voor uw functie of in gevallen waarin de uitvoering van uw functie de toegestane uitvoeringstijd overschrijdt, kan dezelfde batch wijzigingen opnieuw aan uw functie worden geleverd. Deze fout wordt verwacht. Bekijk de functielogboeken voor indicatie van fouten en zorg ervoor dat u triggerlogboeken hebt ingeschakeld voor meer informatie.
Er is een taakverdeling van leases tussen instanties. Wanneer exemplaren toenemen of afnemen, kan taakverdeling ertoe leiden dat dezelfde batch met wijzigingen wordt geleverd aan meerdere functie-exemplaren. Deze taakverdeling wordt verwacht en moet standaard tijdelijk zijn. De triggerlogboeken bevatten de gebeurtenissen wanneer een exemplaar leases verkrijgt en vrijgeeft.
Het item wordt bijgewerkt. De wijzigingenfeed kan meerdere bewerkingen voor hetzelfde item bevatten. Als het item updates ontvangt, kan het meerdere gebeurtenissen (één voor elke update) ophalen. Een eenvoudige manier om onderscheid te maken tussen verschillende bewerkingen voor hetzelfde item, is door de _lsn eigenschap voor elke wijziging bij te houden. Als de eigenschappen niet overeenkomen, zijn de wijzigingen anders.
Als u alleen items identificeert door id, moet u er rekening mee houden dat de unieke id voor een item de id partitiesleutel en de bijbehorende partitiesleutel is. (Twee items kunnen hetzelfde id hebben, maar een andere partitiesleutel).

Sommige wijzigingen ontbreken in uw trigger

Het kan zijn dat de functie geen enkele wijzigingen heeft opgehaald die zijn opgetreden in uw Azure Cosmos DB for NoSQL-container. Of sommige wijzigingen ontbreken op de bestemming wanneer u ze kopieert. Zo ja, probeer dan de oplossingen in deze sectie.

Zorg ervoor dat logboeken zijn ingeschakeld. Controleer of er geen fouten optreden tijdens de verwerking.
Wanneer uw Azure-functie de wijzigingen ontvangt, worden deze vaak verwerkt en kan het resultaat desgewenst naar een andere bestemming worden verzonden. Wanneer u ontbrekende wijzigingen onderzoekt, moet u ervoor zorgen dat u meet welke wijzigingen worden ontvangen op het opnamepunt. Meet wanneer de Azure-functie wordt gestart, niet op de bestemming.
Als sommige wijzigingen ontbreken op de bestemming, kan dit gedrag erop wijzen dat er een fout optreedt tijdens de uitvoering van de Azure-functie nadat de wijzigingen zijn ontvangen.
- In dit scenario kunt u het beste blokken toevoegen try/catch aan uw code en binnen de lussen die de wijzigingen kunnen verwerken. Als u deze toevoegt, kunt u eventuele fouten voor een bepaalde subset van items detecteren en deze dienovereenkomstig afhandelen (verzend ze naar een andere opslag voor verdere analyse of probeer het opnieuw). U kunt ook beleid voor opnieuw proberen van Azure Functions configureren.
  
  Notitie
  
  De trigger van Azure Functions voor Azure Cosmos DB for NOSQL voert standaard geen batch met wijzigingen opnieuw uit als er een niet-verwerkte uitzondering is opgetreden tijdens de uitvoering van de code. Dit betekent dat de reden dat de wijzigingen niet op de bestemming zijn aangekomen mogelijk zijn omdat u ze niet hebt verwerkt.
Als de bestemming een andere Azure Cosmos DB-container is en u upsert-bewerkingen uitvoert om de items te kopiëren, controleert u de definitie van de partitiesleutel op beide containers. De partitiesleutel op de bewaakte en doelcontainer moet hetzelfde zijn. Upsert-bewerkingen kunnen meerdere bronitems opslaan als één op de bestemming vanwege dit configuratieverschil.
Als u merkt dat de trigger geen wijzigingen heeft ontvangen, is het meest voorkomende scenario dat een andere Azure-functie wordt uitgevoerd. De andere functie kan worden geïmplementeerd in Azure of een functie wordt mogelijk lokaal uitgevoerd op de computer van een ontwikkelaar met exact dezelfde configuratie. Als dit het gevolg is, kan deze functie een subset stelen van de wijzigingen die u zou verwachten dat uw Azure-functie moet worden verwerkt.

Daarnaast kan het scenario worden gevalideerd als u weet hoeveel Exemplaren van de Azure-functie-app u hebt uitgevoerd. Als u de leasecontainer inspecteert en het aantal lease-items erin telt, moeten de afzonderlijke waarden van de eigenschap in deze Owner containers gelijk zijn aan het aantal exemplaren van uw functie-app. Als er meer eigenaren zijn dan bekende exemplaren van de Azure-functie-app, betekent dit dat deze extra eigenaren de wijzigingen 'stelen' zijn.

Een eenvoudige manier om deze situatie te omzeilen, is door een LeaseCollectionPrefix/leaseCollectionPrefix functie toe te passen met een nieuwe of andere waarde of om te testen met een nieuwe leasecontainer.

U moet alle items in uw container opnieuw opstarten en opnieuw verwerken vanaf het begin

Als u alle items in een container vanaf het begin opnieuw wilt verwerken:

Stop uw Azure-functie als deze momenteel wordt uitgevoerd.
Verwijder de documenten in de leaseverzameling (of verwijder en maak de leaseverzameling opnieuw zodat deze leeg is).
Stel het kenmerk StartFromBeginning CosmosDBTrigger in uw functie in op true.
Start de Azure-functie opnieuw op. De functie leest en verwerkt nu alle wijzigingen vanaf het begin.

Als u StartFromBeginning instelt om de Azure-functie te true laten beginnen met het lezen van wijzigingen vanaf het begin van de geschiedenis van de verzameling in plaats van de huidige tijd.

Deze oplossing werkt alleen wanneer er geen leases zijn die al zijn gemaakt (documenten in de verzameling leases).

Het instellen van deze eigenschap heeft true geen effect wanneer er al leases zijn gemaakt. Wanneer een functie in dit scenario wordt gestopt en opnieuw wordt gestart, begint deze met het lezen van het laatste controlepunt, zoals gedefinieerd in de verzameling leases.

Fout: `Binding can be done only with IReadOnlyList<Document> or JArray`

Deze fout treedt op als uw Azure Functions-project een handmatige NuGet-pakketverwijzing bevat naar de Azure Cosmos DB SDK met een versieconflict. Deze fout treedt meestal op omdat het pakket een andere versie heeft dan die van de Azure Cosmos DB-extensie voor Azure Functions.

Als u deze situatie wilt omzeilen, verwijdert u de handmatige NuGet-verwijzing die is toegevoegd en laat u de Azure Cosmos DB SDK-verwijzing oplossen via het Azure Cosmos DB-extensiepakket voor Azure Functions.

Het polling-interval van de Azure-functie wijzigen voor het detecteren van wijzigingen

Zoals eerder in de sectie Uw wijzigingen is uitgelegd, duurt het te lang om te worden ontvangen , slaapt uw Azure-functie gedurende een configureerbare hoeveelheid tijd (standaard 5 seconden) voordat er wordt gecontroleerd op nieuwe wijzigingen (om een hoog RU-verbruik te voorkomen). U kunt deze slaaptijd configureren via de FeedPollDelay/feedPollDelay instelling in de triggerconfiguratie (de waarde is naar verwachting in milliseconden).