Azure Cosmos DB-clientbibliotheek voor JavaScript - versie 4.0.0
/TypeScript
Azure Cosmos DB is een wereldwijd gedistribueerde databaseservice met meerdere modellen waarmee databases voor document-, sleutelwaarde-, kolom- en grafiekdatabases worden ondersteund. Dit pakket is bedoeld voor JavaScript-/TypeScript-toepassingen om te communiceren met SQL API-databases en de JSON-documenten die ze bevatten:
- Cosmos DB-databases maken en de instellingen ervan wijzigen
- Containers maken en wijzigen voor het opslaan van verzamelingen JSON-documenten
- De items (JSON-documenten) in uw containers maken, lezen, bijwerken en verwijderen
- Query's uitvoeren op de documenten in uw database met behulp van SQL-achtige syntaxis
Belangrijke koppelingen:
Aan de slag
Vereisten
Azure-abonnement en Cosmos DB SQL API-account
U moet een Azure-abonnement en een Cosmos DB-account (SQL API) hebben om dit pakket te kunnen gebruiken.
Als u een Cosmos DB SQL API-account nodig hebt, kunt u de Azure Cloud Shell gebruiken om er een te maken met deze Azure CLI-opdracht:
az cosmosdb create --resource-group <resource-group-name> --name <cosmos-database-account-name>
U kunt ook een account maken in Azure Portal
Node.js
Dit pakket wordt gedistribueerd via npm , dat vooraf is geïnstalleerd met NodeJS. U moet Node v10 of hoger gebruiken.
CORS
U moet CORS-regels (Cross-Origin Resource Sharing) instellen voor uw Cosmos DB-account als u wilt ontwikkelen voor browsers. Volg de instructies in het gekoppelde document om nieuwe CORS-regels te maken voor uw Cosmos DB.
Dit pakket installeren
npm install @azure/cosmos
Accountreferenties ophalen
U hebt het eindpunt en de sleutel van uw Cosmos DB-account nodig. U vindt deze in de Azure-portal of gebruik het onderstaande Azure CLI-fragment . Het codefragment is geformatteerd voor de Bash-shell.
az cosmosdb show --resource-group <your-resource-group> --name <your-account-name> --query documentEndpoint --output tsv
az cosmosdb keys list --resource-group <your-resource-group> --name <your-account-name> --query primaryMasterKey --output tsv
Een exemplaar maken van CosmosClient
Interactie met Cosmos DB begint met een exemplaar van de CosmosClient-klasse
const { CosmosClient } = require("@azure/cosmos");
const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });
async function main() {
// The rest of the README samples are designed to be pasted into this function body
}
main().catch((error) => {
console.error(error);
});
Voor het gemak hebben we de key
en endpoint
rechtstreeks in de code opgenomen, maar u wilt deze waarschijnlijk laden vanuit een bestand dat niet in broncodebeheer staat met behulp van een project zoals dotenv of laden vanuit omgevingsvariabelen
In productieomgevingen moeten geheimen zoals sleutels worden opgeslagen in Azure Key Vault
Belangrijkste concepten
Nadat u een CosmosClient hebt geïnitialiseerd, kunt u communiceren met de primaire resourcetypen in Cosmos DB:
Database: een Cosmos DB-account kan meerdere databases bevatten. Wanneer u een database maakt, geeft u de API op die u wilt gebruiken bij de interactie met de bijbehorende documenten: SQL, MongoDB, Gremlin, Cassandra of Azure Table. Gebruik het databaseobject om de containers te beheren.
Container: een container is een verzameling JSON-documenten. U kunt items in een container maken (invoegen), lezen, bijwerken en verwijderen met behulp van methoden in het containerobject .
Item: Een item is een JSON-document dat is opgeslagen in een container. Elk item moet een
id
sleutel bevatten met een waarde die het item in de container uniek identificeert. Als u geen opgeeft, wordt er automatisch eenid
gegenereerd door de SDK.
Zie Werken met Azure Cosmos-databases, -containers en -items voor meer informatie over deze resources.
Voorbeelden
De volgende secties bevatten verschillende codefragmenten die betrekking hebben op enkele van de meest voorkomende Cosmos DB-taken, waaronder:
- Een database maken
- Een container maken
- Partitiesleutels gebruiken
- Items invoegen
- Query's uitvoeren voor documenten
- Een item lezen
- Item verwijderen
- CRUD op container met hiërarchische partitiesleutel
Een database maken
Nadat u uw CosmosClient hebt geverifieerd, kunt u met elke resource in het account werken. Met het onderstaande codefragment wordt een NOSQL API-database gemaakt.
const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
console.log(database.id);
Een container maken
In dit voorbeeld wordt een container met standaardinstellingen gemaakt
const { container } = await database.containers.createIfNotExists({ id: "Test Database" });
console.log(container.id);
Partitiesleutels gebruiken
In dit voorbeeld ziet u verschillende typen partitiesleutels die worden ondersteund.
await container.item("id", "1").read(); // string type
await container.item("id", 2).read(); // number type
await container.item("id", true).read(); // boolean type
await container.item("id", {}).read(); // None type
await container.item("id", undefined).read(); // None type
await container.item("id", null).read(); // null type
Als de partitiesleutel uit één waarde bestaat, kan deze worden opgegeven als een letterlijke waarde of als een matrix.
await container.item("id", "1").read();
await container.item("id", ["1"]).read();
Als de partitiesleutel uit meer dan één waarde bestaat, moet deze worden opgegeven als een matrix.
await container.item("id", ["a", "b"]).read();
await container.item("id", ["a", 2]).read();
await container.item("id", [{}, {}]).read();
await container.item("id", ["a", {}]).read();
await container.item("id", [2, null]).read();
Items invoegen
Als u items in een container wilt invoegen, geeft u een object met uw gegevens door aan Items.upsert. Voor de Azure Cosmos DB-service moet elk item een id
sleutel hebben. Als u er geen opgeeft, genereert de SDK automatisch een id
.
In dit voorbeeld worden verschillende items in de container ingevoegd
const cities = [
{ id: "1", name: "Olympia", state: "WA", isCapitol: true },
{ id: "2", name: "Redmond", state: "WA", isCapitol: false },
{ id: "3", name: "Chicago", state: "IL", isCapitol: false }
];
for (const city of cities) {
await container.items.create(city);
}
Een item lezen
Als u één item uit een container wilt lezen, gebruikt u Item.read. Dit is een goedkopere bewerking dan het gebruik van SQL om query's uit te voeren op id
.
await container.item("1", "1").read();
CRUD op container met hiërarchische partitiesleutel
Een container maken met een hiërarchische partitiesleutel
const containerDefinition = {
id: "Test Database",
partitionKey: {
paths: ["/name", "/address/zip"],
version: PartitionKeyDefinitionVersion.V2,
kind: PartitionKeyKind.MultiHash,
},
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);
Een item invoegen met een hiërarchische partitiesleutel die is gedefinieerd als - ["/name", "/address/zip"]
const item = {
id: 1,
name: 'foo',
address: {
zip: 100
},
active: true
}
await container.items.create(item);
Als u één item wilt lezen uit een container met een hiërarchische partitiesleutel die is gedefinieerd als - ["/name", "/address/zip"],
await container.item("1", ["foo", 100]).read();
Een query uitvoeren op een item met een hiërarchische partitiesleutel met een hiërarchische partitiesleutel die is gedefinieerd als - ["/name", "/address/zip"],
const { resources } = await container.items
.query("SELECT * from c WHERE c.active = true", {
partitionKey: ["foo", 100],
})
.fetchAll();
for (const item of resources) {
console.log(`${item.name}, ${item.address.zip} `);
}
Een item verwijderen
Als u items uit een container wilt verwijderen, gebruikt u Item.delete.
// Delete the first item returned by the query above
await container.item("1").delete();
Een query uitvoeren op de database
Een Cosmos DB SQL API-database ondersteunt het uitvoeren van query's op de items in een container met Items.query met behulp van SQL-achtige syntaxis:
const { resources } = await container.items
.query("SELECT * from c WHERE c.isCapitol = true")
.fetchAll();
for (const city of resources) {
console.log(`${city.name}, ${city.state} is a capitol `);
}
Voer geparameteriseerde query's uit door een object met de parameters en hun waarden door te geven aan Items.query:
const { resources } = await container.items
.query({
query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
parameters: [{ name: "@isCapitol", value: true }]
})
.fetchAll();
for (const city of resources) {
console.log(`${city.name}, ${city.state} is a capitol `);
}
Zie Query's uitvoeren op Azure Cosmos DB-gegevens met SQL-query's voor meer informatie over het uitvoeren van query's op Cosmos DB-databases met behulp van de SQL-API.
Pull-model voor wijzigingenfeed
Wijzigingenfeed kan worden opgehaald voor een partitiesleutel, een feedbereik of een hele container.
Als u de wijzigingenfeed wilt verwerken, maakt u een exemplaar van ChangeFeedPullModelIterator
. Wanneer u voor het eerst maakt ChangeFeedPullModelIterator
, moet u een vereiste changeFeedStartFrom
waarde in de ChangeFeedIteratorOptions
opgeven die bestaat uit zowel de beginpositie voor het lezen van wijzigingen als de resource (een partitiesleutel of een FeedRange) waarvoor wijzigingen moeten worden opgehaald. U kunt eventueel in ChangeFeedIteratorOptions
gebruiken maxItemCount
om het maximum aantal items per pagina in te stellen.
Opmerking: als er geen changeFeedStartFrom
waarde is opgegeven, wordt changefeed opgehaald voor een hele container van Now().
Er zijn vier startposities voor de wijzigingenfeed:
Beginning
// Signals the iterator to read changefeed from the beginning of time.
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Beginning();
}
const iterator = container.getChangeFeedIterator(options);
Time
// Signals the iterator to read changefeed from a particular point of time.
const time = new Date("2023/09/11") // some sample date
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Time(time);
}
Now
// Signals the iterator to read changefeed from this moment onward.
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Now();
}
Continuation
// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token recieved from previous request";
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken);
}
Hier volgt een voorbeeld van het ophalen van een wijzigingenfeed voor een partitiesleutel
const partitionKey = "some-partition-Key-value";
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Beginning(partitionKey),
};
const iterator = container.items.getChangeFeedIterator(options);
while (iterator.hasMoreResults) {
const response = await iterator.readNext();
// process this response
}
Omdat de wijzigingenfeed in feite een oneindige lijst met items is die alle toekomstige schrijfbewerkingen en updates omvat, is de waarde van hasMoreResults
altijd true
. Wanneer u de wijzigingenfeed probeert te lezen en er geen nieuwe wijzigingen beschikbaar zijn, ontvangt u een antwoord met NotModified
de status.
Meer gedetailleerde gebruiksrichtlijnen en voorbeelden van wijzigingenfeed vindt u hier.
Foutafhandeling
De SDK genereert verschillende typen fouten die kunnen optreden tijdens een bewerking.
ErrorResponse
wordt gegenereerd als het antwoord van een bewerking een foutcode van >=400 retourneert.TimeoutError
wordt gegenereerd als Afbreken intern wordt aangeroepen vanwege een time-out.AbortError
wordt gegenereerd als een gebruiker een signaal heeft doorgegeven waardoor de afbreeking is veroorzaakt.RestError
wordt gegenereerd in het geval van een storing van de onderliggende systeemoproep vanwege netwerkproblemen.- Fouten die worden gegenereerd door eventuele devDependencies. Voor bijvoorbeeld
@azure/identity
pakket kan gooienCredentialUnavailableError
.
Hieronder volgt een voorbeeld voor het afhandelen van fouten van het type ErrorResponse
, TimeoutError
, AbortError
en RestError
.
try {
// some code
} catch (err) {
if (err instanceof ErrorResponse) {
// some specific error handling.
} else if (err instanceof RestError) {
// some specific error handling.
}
// handle other type of errors in similar way.
else {
// for any other error.
}
}
Het is belangrijk om deze fouten correct af te handelen om ervoor te zorgen dat uw toepassing probleemloos kan herstellen van eventuele fouten en kan blijven functioneren zoals verwacht. Meer informatie over een aantal van deze fouten en de mogelijke oplossingen vindt u hier.
Problemen oplossen
Algemeen
Wanneer u werkt met Cosmos DB-fouten die door de service worden geretourneerd, komen overeen met dezelfde HTTP-statuscodes die zijn geretourneerd voor REST API-aanvragen:
HTTP-statuscodes voor Azure Cosmos DB
Conflicten
Als u bijvoorbeeld een item probeert te maken met een id
dat al in gebruik is in uw Cosmos DB-database, wordt er een 409
fout geretourneerd die het conflict aangeeft. In het volgende codefragment wordt de fout mooi verwerkt door de uitzondering vast te leggen en aanvullende informatie over de fout weer te geven.
try {
await containers.items.create({ id: "existing-item-id" });
} catch (error) {
if (error.code === 409) {
console.log("There was a conflict with an existing item");
}
}
Transpileren
De Azure SDK's zijn ontworpen ter ondersteuning van ES5 JavaScript-syntaxis en LTS-versies van Node.js. Als u ondersteuning nodig hebt voor eerdere JavaScript-runtimes, zoals Internet Explorer of Node 6, moet u de SDK-code transpileren als onderdeel van uw buildproces.
Tijdelijke fouten verwerken met nieuwe pogingen
Tijdens het werken met Cosmos DB kunnen tijdelijke fouten optreden die worden veroorzaakt door frequentielimieten die worden afgedwongen door de service, of andere tijdelijke problemen, zoals netwerkstoringen. Raadpleeg voor meer informatie over het verwerken van dit soort fouten Patroon voor opnieuw proberen in de handleiding Cloudontwerppatronen en de verwante Patroon Circuitonderbreker.
Logboekregistratie
Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL
omgevingsvariabele in op info
. Logboekregistratie kan ook worden ingeschakeld tijdens runtime door aan te roepen setLogLevel
in de @azure/logger
. AZURE_LOG_LEVEL
Zorg ervoor dat u deze instelt voordat de logboekregistratiebibliotheek wordt geïnitialiseerd.
Geef deze in het ideale geval door via de opdrachtregel, als u bibliotheken zoals dotenv
gebruikt, moet u ervoor zorgen dat dergelijke bibliotheken zijn geïnitialiseerd voordat u de bibliotheek in logboekregistratie opgeeft.
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.
Diagnostiek
De functie Cosmos Diagnostics biedt uitgebreide inzichten in al uw clientbewerkingen. Een CosmosDiagnostics-object wordt toegevoegd aan het antwoord van alle clientbewerkingen. Zoals
- Reponse van puntzoekbewerking -
item.read()
,container.create()
,database.delete()
- Querybewerking-reponse -
queryIterator.fetchAll()
, - Bulk- en batchbewerkingen -
item.batch()
. - Fout-/uitzonderingsreactieobjecten.
Een CosmosDiagnostics-object wordt toegevoegd aan het antwoord van alle clientbewerkingen. Er zijn 3 diagnostische cosmos-niveaus, info, foutopsporing en onveilige foutopsporing. Hierbij is alleen informatie bedoeld voor productiesystemen en zijn foutopsporing en foutopsporing onveilig bedoeld om te worden gebruikt tijdens ontwikkeling en foutopsporing, omdat deze aanzienlijk hogere resources verbruiken. Cosmos Diagnostic-niveau kan op 2 manieren worden ingesteld
- Programmatisch
const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });
- Omgevingsvariabelen gebruiken. (Diagnostisch niveau ingesteld door omgevingsvariabele heeft een hogere prioriteit dan het instellen ervan via clientopties.)
export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"
Cosmos Diagnostic heeft drie leden
ClientSideRequestStatistics Type: Bevat statistische diagnostische gegevens, waaronder metagegevenszoekacties, nieuwe pogingen, eindpunten die zijn benaderd en aanvraag- en antwoordstatistieken, zoals de grootte en duur van de nettolading. (wordt altijd verzameld, kan worden gebruikt in productiesystemen.)
DiagnosticNode: is een structuur die lijkt op een structuur die gedetailleerde diagnostische gegevens vastlegt.
har
Vergelijkbaar met opname die aanwezig is in browsers. Deze functie is standaard uitgeschakeld en is alleen bedoeld voor het opsporen van fouten in niet-productieomgevingen. (verzameld op diagnostisch niveau foutopsporing en foutopsporing onveilig)ClientConfig: legt essentiële informatie vast met betrekking tot de configuratie-instellingen van de client tijdens de initialisatie van de client. (verzameld op diagnostisch niveau foutopsporing en foutopsporing onveilig)
Zorg ervoor dat u het diagnostische niveau debug-unsafe
nooit instelt op in de productieomgeving, omdat dit niveau CosmosDiagnostics
nettoladingen van aanvragen en antwoorden vastlegt en als u ervoor kiest om het te registreren (het wordt standaard geregistreerd door @azure/logger op verbose
niveau). Deze nettoladingen kunnen worden vastgelegd in uw logboeksinks.
Diagnostische gegevens gebruiken
- Aangezien
diagnostics
wordt toegevoegd aan alle antwoordobjecten. U kunt programmatisch toegang krijgenCosmosDiagnostic
als volgt.
// For point look up operations
const { container, diagnostics: containerCreateDiagnostic } =
await database.containers.createIfNotExists({
id: containerId,
partitionKey: {
paths: ["/key1"],
},
});
// For Batch operations
const operations: OperationInput[] = [
{
operationType: BulkOperationType.Create,
resourceBody: { id: 'A', key: "A", school: "high" },
},
];
const response = await container.items.batch(operations, "A");
// For query operations
const queryIterator = container.items.query("select * from c");
const { resources, diagnostics } = await queryIterator.fetchAll();
// While error handling
try {
// Some operation that might fail
} catch (err) {
const diagnostics = err.diagnostics
}
- U kunt ook registreren
diagnostics
met behulp van@azure/logger
, diagnostische gegevens worden altijd geregistreerd met behulp van@azure/logger
niveauverbose
. Dus als u diagnostisch niveau instelt opdebug
ofdebug-unsafe
en@azure/logger
niveau opverbose
,diagnostics
wordt geregistreerd.
Volgende stappen
Meer voorbeeldcode
Er zijn verschillende voorbeelden beschikbaar in de GitHub-opslagplaats van de SDK. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak voorkomen tijdens het werken met Cosmos DB:
- Databasebewerkingen
- Containerbewerkingen
- Itembewerkingen
- Indexering configureren
- Een containerwijzigingsfeed lezen
- Opgeslagen procedures
- Instellingen voor database-/containerdoorvoer wijzigen
- Schrijfbewerkingen in meerdere regio's
Beperkingen
De onderstaande functies worden momenteel niet ondersteund. Raadpleeg de sectie Tijdelijke oplossingen hieronder voor alternatieve opties.
Beperkingen van gegevensvlak:
- Query's met COUNT uit een DISTINCT-subquery
- Toegang tot directe TCP-modus
- Statistische query's voor meerdere partities, zoals sorteren, tellen en uniek, bieden geen ondersteuning voor vervolgtokens. Streambare query's, zoals SELECT * FROM WHERE , ondersteuning voor vervolgtokens. Zie de sectie Tijdelijke oplossing voor het uitvoeren van niet-streambare query's zonder een vervolgtoken.
- Wijzigingenfeed: Processor
- Wijzigingenfeed: sleutelwaarden voor meerdere partities lezen
- Feed pull-model alle versies wijzigen en modus verwijderen #27058
- Ondersteuning voor pull-model van wijzigingenfeed voor gedeeltelijke hiërarchische partitiesleutels #27059
- ORDER BY voor meerdere partities voor gemengde typen
- Metrische gegevens van CollectionSizeUsage, DatabaseUsage en DocumentUsage ophalen
- Georuimtelijke index maken
- Doorvoer automatisch schalen bijwerken
Beperkingen van besturingsvlak:
Tijdelijke oplossingen
Vervolgtoken voor query's tussen partities
U kunt query's voor meerdere partities bereiken met ondersteuning voor vervolgtoken met behulp van het zij-autopatroon. Met behulp van dit patroon kunnen toepassingen ook worden samengesteld met heterogene onderdelen en technologieën.
Niet-stremable query voor meerdere partities uitvoeren
Als u niet-streambare query's wilt uitvoeren zonder vervolgtokens te gebruiken, kunt u een query-iterator maken met de vereiste queryspecificatie en -opties. De volgende voorbeeldcode laat zien hoe u een query-iterator gebruikt om alle resultaten op te halen zonder dat u een vervolgtoken nodig hebt:
const querySpec = {
query: "SELECT * FROM c WHERE c.status = @status",
parameters: [{ name: "@status", value: "active" }],
};
const queryOptions = {
maxItemCount: 10, // maximum number of items to return per page
enableCrossPartitionQuery: true,
};
const querIterator = await container.items.query(querySpec, queryOptions);
while (querIterator.hasMoreResults()) {
const { resources: result } = await querIterator.fetchNext();
//Do something with result
}
Deze methode kan ook worden gebruikt voor streambare query's.
Besturingsvlakbewerkingen
Normaal gesproken kunt u Azure Portal, Azure Cosmos DB Resource Provider REST API, Azure CLI of PowerShell gebruiken voor de niet-ondersteunde beperkingen van het besturingsvlak.
Aanvullende documentatie
Zie de Azure Cosmos DB-documentatie op docs.microsoft.com voor uitgebreidere documentatie over de Cosmos DB-service .
Handige koppelingen
- Welkom bij Azure Cosmos DB
- Snel starten
- Zelfstudie
- Voorbeelden
- Inleiding tot het resourcemodel van de Azure Cosmos DB-service
- Inleiding tot SQL API van Azure Cosmos DB Service
- Partitionering
- API-documentatie
Bijdragen
Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de handleiding voor bijdragen voor meer informatie over het bouwen en testen van de code.
Azure SDK for JavaScript
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor