Azure Cosmos DB client library for JavaScript - version 4.10.0

/TypeScript

Az Azure Cosmos DB egy globálisan elosztott, többmodelles adatbázis-szolgáltatás, amely támogatja a dokumentum-, kulcsérték-, szélesoszlopos és gráf adatbázisokat. Ez a csomag JavaScript-/TypeScript-alkalmazások számára készült, SQL API--adatbázisokkal és az általuk tárolt JSON-dokumentumokkal való interakcióhoz:

• Cosmos DB-adatbázisok létrehozása és beállításaik módosítása
• Tárolók létrehozása és módosítása JSON-dokumentumok gyűjteményeinek tárolásához
• A tárolókban lévő elemek (JSON-dokumentumok) létrehozása, olvasása, frissítése és törlése
• Az adatbázis dokumentumainak lekérdezése SQL-szerű szintaxissal

Főbb hivatkozások:

• csomag (npm)
• API-referenciadokumentáció
• termékdokumentáció

Kezdetekhez

Előfeltételek

Azure Subscription and Cosmos DB SQL API Account

Ehhez ehhez Azure előfizetés és Cosmos DB fiók (SQL API) kell rendelkeznie.

Ha szükséged van Cosmos adatbázis SQL API fiókra, a Azure Cloud Shell segítségével létrehozhatsz egyet ezen Azure CLI parancsnak:

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-database-account-name>

Vagy létrehozhatsz fiókot a Azure Portal

NodeJS

Ez a csomag npm keresztül van elosztva, amely előre telepítve van NodeJS LTS-verzióval.

CORS

Ha böngészőkre van szüksége, be kell állítania több forrásból származó erőforrás-megosztási (CORS) szabályokat a Cosmos DB-fiókhoz. A csatolt dokumentumban található utasításokat követve hozzon létre új CORS-szabályokat a Cosmos DB-hez.

A csomag telepítése

npm install @azure/cosmos

Fiók hitelesítő adatainak lekérése

Szüksége lesz a Cosmos DB--fiókvégpontra és kulcs. Ezeket megtalálhatod a Azure Portal vagy az alábbi Azure CLI részletet használod. A kódrészlet a Bash-rendszerhéjhoz van formázva.

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

CosmosClient-példány létrehozása

A Cosmos DB-vel való interakció a CosmosClient osztály egy példányával kezdődik

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

Az egyszerűség kedvéért a key és a endpoint közvetlenül a kódba is belefoglaltuk, de valószínűleg olyan fájlból szeretné betölteni őket, amely nem forrásvezérléssel rendelkezik egy projekttel, például dotenv vagy környezeti változókból való betöltéssel

Gyártási környezetben a titkokat, például kulcsokat Azure Key Vault

Főbb fogalmak

Miután inicializált egy CosmosClient, használhatja a Cosmos DB elsődleges erőforrástípusait:

• Adatbázis-: A Cosmos DB-fiókok több adatbázist is tartalmazhatnak. Amikor adatbázist hozol létre, megadod azt az API-t, amit használni szeretnél a dokumentumokkal való interakció során: SQL, MongoDB, Gremlin, Cassandra vagy Azure Table. A tárolók kezeléséhez használja a Database objektumot.

• Tároló: A tároló JSON-dokumentumok gyűjteménye. A tárolóban lévő elemeket a Tároló objektum metódusainak használatával hozhatja létre (szúrhatja be), olvashatja, frissítheti és törölheti.

• Elem: Az elem egy tárolóban tárolt JSON-dokumentum. Minden elemnek tartalmaznia kell egy id kulcsot egy olyan értékkel, amely egyedileg azonosítja az elemet a tárolóban. Ha nem ad meg id, az SDK automatikusan létrehoz egyet.

További információért ezekről az erőforrásokról lásd: Working with Azure Cosmos adatbázisok, konténerek és elemek.

Példák

A következő szakaszok számos kódrészletet biztosítanak, amelyek a leggyakoribb Cosmos DB-feladatokat fedik le, többek között:

• Adatbázis létrehozása
• Tároló létrehozása
• Partíciókulcsok használata
• Elemek beszúrása
• dokumentumok lekérdezése
• Elem olvasása
• Elem törlése
• CRUD-t a tárolón hierarchikus partíciókulcsú
• Kizárt helyek használata

Adatbázis létrehozása

A CosmosClienthitelesítése után a fiók bármely erőforrásával dolgozhat. Az alábbi kódrészlet létrehoz egy NOSQL API-adatbázist.

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

Tároló létrehozása

Ez a példa létrehoz egy alapértelmezett beállításokkal rendelkező tárolót

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

Partíciókulcsok használata

Ez a példa a támogatott partíciókulcsok különböző típusait mutatja be.

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

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

Ha a partíciókulcs egyetlen értékből áll, akkor konstans értékként vagy tömbként is adható meg.

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

await container.item("id", "1").read();
await container.item("id", ["1"]).read();

Ha a partíciókulcs több értékből áll, tömbként kell megadni.

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

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();

Elemek beszúrása

Ha elemeket szeretne beszúrni egy tárolóba, adja át az adatokat tartalmazó objektumot Items.upsert. A Azure Cosmos DB szolgáltatáshoz minden tárgynak legyen id kulcsa. Ha nem ad meg egyet, az SDK automatikusan létrehoz egy id.

Ez a példa több elemet szúr be a tárolóba

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

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);
}

Elem olvasása

Ha egyetlen elemet szeretne beolvasni egy tárolóból, használja Item.read. Ez kevésbé költséges művelet, mint az SQL használata idlekérdezéséhez.

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

await container.item("1", "1").read();

CRUD a tárolón hierarchikus partíciókulccsal

Tároló létrehozása hierarchikus partíciókulccsal

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

Elem beszúrása hierarchikus partíciókulccsal – ["/name", "/address/zip"]

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

const item = {
  id: "1",
  name: "foo",
  address: {
    zip: 100,
  },
  active: true,
};
await container.items.create(item);

Egyetlen elem beolvasása egy tárolóból a következőként definiált hierarchikus partíciókulccsal: ["/name", "/address/zip"],

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

await container.item("1", ["foo", 100]).read();

Hierarchikus partíciókulcsú elem lekérdezése a következőként definiált hierarchikus partíciókulccsal: - ["/name", "/address/zip"],

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
    partitionKey: ["foo", 100],
  })
  .fetchAll();

Elem törlése

Egy tároló elemeinek törléséhez használja Item.delete.

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

// Delete the first item returned by the query above
await container.item("1").delete();

Az adatbázis lekérdezése

A Cosmos DB SQL API-adatbázis támogatja a tároló elemeinek lekérdezését Items.query SQL-szerű szintaxissal:

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();

Paraméteres lekérdezések végrehajtása a paramétereket és értékeiket tartalmazó objektum Items.query:

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }],
  })
  .fetchAll();

Megjegyzés: A folytatási tokenek lekérdezésekhez való használatához győződjön meg róla, hogy ez enableQueryControl a lekérdezési opciókban be van állítva true . Ez lehetővé teszi a lekérdezés folytatási tokeneinek lekérését nagy eredményhalmazon keresztüli oldalozáshoz.

Íme egy példa folytatási tokenek használatára a következőkkel enableQueryControl:

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const queryIterator = container.items.query("SELECT * from c", {
  maxItemCount: 10,
  enableQueryControl: true,
  forceQueryPlan: true,
});

let pageCount = 0;
while (queryIterator.hasMoreResults()) {
  pageCount++;
  const { resources, continuationToken } = await queryIterator.fetchNext();
  console.log(`Page ${pageCount} has ${resources.length} items`);
  // continuationToken can be saved and used later to resume from where you left off
}

Különleges eset: SORRENDBEN lekérdezések

ORDER BY lekérdezések esetén enableQueryControl figyelj arra, hogy a folytatási token viselkedése speciális kezelést igényel:

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const queryIterator = container.items.query("SELECT * from c ORDER BY c.id", {
  maxItemCount: 10,
  enableQueryControl: true,
  forceQueryPlan: true,
});

let pageCount = 0;
while (queryIterator.hasMoreResults()) {
  pageCount++;
  const { resources, continuationToken } = await queryIterator.fetchNext();
  if (resources.length > 0) {
    // Process results
    // Safe to use continuationToken after receiving data
    if (continuationToken) {
      // Can persist token for resuming later
    }
  }
}

Fontos: ORDER BY lekérdezésekkel való használatkor enableQueryControl :

• A resources tömb és continuationToken az első hívások során üres és undefined visszavágó lehet.
• Ez azért történik, mert a lekérdezésnek az eredményeket a partíciók között kell össze kell vonnia, mielőtt visszatérne
• Mindig ellenőrizd resources.length > 0 , mielőtt a folytatási tokenre támaszkodnál
• Használd forceQueryPlan: true a lekérdezési opciókat, hogy következetes lekérdezési végrehajtási viselkedést biztosíts a partíciók között, ami segít a folytatási token stabilitásában

További információért a Cosmos DB adatbázisok SQL API használatával történő lekérdezéséről lásd: Query Azure Cosmos DB data SQL queries.

Változáscsatorna lekéréses modelljének módosítása

A változáscsatorna lekérhető egy partíciókulcshoz, egy adatcsatornatartományhoz vagy egy teljes tárolóhoz.

A változáscsatorna feldolgozásához hozzon létre egy ChangeFeedPullModelIterator-példányt. Amikor először hoz létre ChangeFeedPullModelIterator, meg kell adnia egy szükséges changeFeedStartFrom értéket a ChangeFeedIteratorOptions belül, amely a módosítások olvasásának kezdő pozíciójából és az erőforrásból (partíciókulcsból vagy FeedRange-ból) áll, amelyhez a módosításokat le kell kérni. A maxItemCountChangeFeedIteratorOptions is használhatja a laponként fogadott elemek maximális számának beállításához.

Megjegyzés: Ha nincs megadva changeFeedStartFrom érték, akkor a rendszer lekéri a changefeed függvényt egy teljes tárolóhoz a Now() fájlból.

A változáscsatorna négy kezdőpozícióval érhető el:

• Beginning

import { ChangeFeedStartFrom } from "@azure/cosmos";

const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
};

• Time

import { ChangeFeedStartFrom } from "@azure/cosmos";

const time = new Date("2023/09/11"); // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time),
};

• Now

import { ChangeFeedStartFrom } from "@azure/cosmos";

// Signals the iterator to read changefeed from this moment onward.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Now(),
};

• Continuation

import { ChangeFeedStartFrom } from "@azure/cosmos";

// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token received from previous request";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken),
};

Íme egy példa a partíciókulcs változáscsatornájának beolvasására

import {
  CosmosClient,
  PartitionKeyDefinitionVersion,
  PartitionKeyKind,
  ChangeFeedStartFrom,
} from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

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
}

Mivel a változáscsatorna gyakorlatilag az összes jövőbeli írást és frissítést magában foglaló elemek végtelen listája, a hasMoreResults értéke mindig true. Amikor megpróbálja elolvasni a változáscsatornát, és nincsenek új módosítások, NotModified állapotú választ kap.

Részletesebb használati irányelvek és példák a változáscsatorna itt találhatók.

Kizárt helyek használata

A kérés szintjén az excludedLocations opció lehetővé teszi a felhasználó számára, hogy egy vagy több Azure régiót határozzon meg, amelyeket ki kell zárni a kérés kiszolgálásából. Ez olyan esetekben hasznos, amikor a felhasználó megfelelőségi, késési vagy rendelkezésre állási aggályok miatt el szeretne kerülni bizonyos régiókat. Ha be van állítva, Cosmos DB más elérhető régiókba irányítja a kérést, javítva az adattárolási hely és a feladatátvételi viselkedés szabályozását.

excludedLocations csak akkor van alkalmazva, ha enableEndPointDiscovery igaz értékre van állítva.

Ez a példa a kizárt helyeket támogató különböző API-kat mutatja be.

import { CosmosClient, ChangeFeedStartFrom } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const city = { id: "1", name: "Olympia", state: "WA" };
await container.items.upsert(city, { excludedLocations: ["Test Region"] });

const iterator = container.items.getChangeFeedIterator({
  excludedLocations: ["Test Region"],
  maxItemCount: 1,
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
});

const response = await iterator.readNext();

Előzetes verziójú funkciók

Néhány fejlesztés alatt álló képesség is elérhető a enablePreviewFeatures opció mögött.CosmosClientOptions Az előzetes funkciók opt-inosak, visszafelé inkompatibilis módon változhatnak a kiadások között, és nem ajánlottak gyártási használatra.

Jelenleg támogatott előnézeti funkciók:

Feature	enablePreviewFeatures kulcs	Requirements
Szemantikai reranking	semanticRerank	AAD hitelesítés (aadCredentials)

Szemantikai reranking

Container.semanticRerank(rerankContext, documents, options) a Cosmos DB Következtetési Szolgáltatás segítségével pontozza és újrasorolja a dokumentumhalmazt, amelyek relevanciájuk alapján egy lekérdezéshez kapcsolódik. Engedélyezd úgy, hogy beállítod a semanticRerank kulcsot az alábbi enablePreviewFeaturesalat alatt:

• inferenceEndpoint (kötelező) — a fiókod következtetési szolgáltatásának végpontja.
• inferenceRequestTimeout (opcionális, millimásodperc; alapértelmezett 5000) — egy egykísérletes időkérés próbálkozás nélkül; a lassabb válasz HTTP-vel 408nem működik.

A szemantikai rerangsorolás AAD hitelesítést igényel, ezért passz aadCredentials az ügyfél építésekor. Az eredmény és a hibák érvényesek CosmosDiagnostics a műveletben.

import { DefaultAzureCredential } from "@azure/identity";
import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const aadCredentials = new DefaultAzureCredential();
const client = new CosmosClient({
  endpoint,
  aadCredentials,
  enablePreviewFeatures: {
    semanticRerank: {
      inferenceEndpoint: "https://your-account.<region>.dbinference.azure.com",
    },
  },
});

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const queryResults = ["doc1 JSON", "doc2 JSON", "doc3 JSON"];
const result = await container.semanticRerank(
  "most economical with multiple adjustments",
  queryResults,
  { return_documents: true, top_k: 10, sort: true },
);
// Access the top-ranked document
if (result.rerankScores.length > 0) {
  const topResult = result.rerankScores[0];
  const topScore = topResult.score;
  const topDocument = topResult.document;
  if (topDocument) {
    console.log("Top-ranked document:", topDocument);
  }
  console.log("Top score:", topScore);
}

Hibakezelés

Az SDK különböző típusú hibákat generál, amelyek egy művelet során fordulhatnak elő.

1. ErrorResponse akkor jelenik meg, ha egy művelet válasza >=400 hibakódot ad vissza.
2. TimeoutError akkor történik, ha a megszakítást az időtúllépés miatt belsőleg hívjuk meg.
3. AbortError a rendszer akkor küldi el, ha a felhasználó által átadott jel okozta a megszakítást.
4. RestError az alapul szolgáló rendszerhívás hálózati problémák miatti meghibásodása esetén történik.
5. A devDependencies által generált hibák. Például: @azure/identity csomag dobhat CredentialUnavailableError.

Az alábbi példa a ErrorResponse, TimeoutError, AbortErrorés RestErrortípusú hibák kezelésére használható.

import { ErrorResponse, RestError } from "@azure/cosmos";

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.
  }
}

Fontos, hogy megfelelően kezelje ezeket a hibákat, hogy az alkalmazás zökkenőmentesen helyreálljon a hibákból, és a várt módon működjön tovább. Ezekről a hibákról és azok lehetséges megoldásairól itt talál további részleteket, itt.

Hibaelhárítás

Általános

Amikor a szolgáltatás által visszaadott Cosmos DB-hibákat használja, a REST API-kérésekhez visszaadott HTTP-állapotkódoknak felel meg:

HTTP-állapotkódok az Azure Cosmos DB-hez

Konfliktusok

Ha például egy olyan id használatával próbál létrehozni egy elemet, amely már használatban van a Cosmos DB-adatbázisban, a rendszer egy 409 hibát ad vissza, amely az ütközést jelzi. A következő kódrészletben a rendszer a kivétel elfogásával és a hibával kapcsolatos további információk megjelenítésével kezeli a hibát.

import { CosmosClient, ErrorResponse, RestError } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

try {
  await container.items.create({ id: "existing-item-id" });
} catch (error) {
  const err = error as ErrorResponse | RestError;
  if (err.code === 409) {
    console.log("There was a conflict with an existing item");
  }
}

Fordítás

Az Azure SDK-k az ES5 JavaScript szintaxisának és a Node.js LTS verzióinak támogatására készültek. Ha korábbi JavaScript futtatási időkhöz, például az Internet Explorer-hez vagy a Node 6-hoz szükséged van, akkor az SDK kódot a build folyamat részeként kell átültetned.

Átmeneti hibák kezelése újrapróbálkozással

A Cosmos DB használata során átmeneti hibákba ütközhet, amelyeket a szolgáltatás által kényszerített sebességkorlátok okoznak, vagy egyéb átmeneti problémák, például hálózati kimaradások. Az ilyen típusú hibák kezelésével kapcsolatos információkért tekintse meg Újrapróbálkozási minta a Felhőtervezési minták útmutatójában, valamint a kapcsolódó megszakító minta.

Fakitermelés

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a AZURE_LOG_LEVEL környezeti változót info. A naplózás futásidőben is engedélyezhető a setLogLevel@azure/logger meghívásával. A AZURE_LOG_LEVEL használata közben mindenképpen állítsa be a naplózási kódtár inicializálása előtt. Ideális esetben adja át a parancssoron, ha olyan kódtárakat használ, mint a dotenv a kódtár naplózása előtt győződjön meg arról, hogy az ilyen kódtárak inicializálva vannak.

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

A naplók engedélyezéséhez részletes utasításokat kereshetsz a @azure/logger csomag docs oldalán.

Diagnosztika

A Cosmos Diagnostics szolgáltatás továbbfejlesztett betekintést nyújt az összes ügyfélműveletbe. A rendszer hozzáad egy CosmosDiagnostics-objektumot az összes ügyfélművelet válaszához. például

• Pontkeresési művelet ismétlése – item.read(), container.create(), database.delete()
• Lekérdezési művelet ismétlése –queryIterator.fetchAll(),
• Tömeges és Batch-műveletek –item.batch().
• Hiba-/kivételválasz-objektumok.

A rendszer hozzáad egy CosmosDiagnostics-objektumot az összes ügyfélművelet válaszához. 3 Cosmos diagnosztikai szint, információ, hibakeresés és hibakeresés nem biztonságos. Ahol csak az éles rendszerekhez készült információk, és a hibakeresés és a hibakeresés nem biztonságos, a fejlesztés és a hibakeresés során kell használni, mivel jelentősen nagyobb erőforrásokat használnak fel. A Cosmos diagnosztikai szintje kétféleképpen állítható be

• Programozott módon

import { CosmosClient, CosmosDbDiagnosticLevel } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({
  endpoint,
  key,
  diagnosticLevel: CosmosDbDiagnosticLevel.debug,
});

• Környezeti változók használata. (A környezeti változó által beállított diagnosztikai szint nagyobb prioritással rendelkezik az ügyfélbeállításokon keresztüli beállítással szemben.)

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

A Cosmos Diagnosticnak három tagja van

• ClientSideRequestStatistics típus: Összesíti a diagnosztikai adatokat, beleértve a metaadatok keresését, az újrapróbálkozásokat, a felkeresett végpontokat, valamint a kérelem- és válaszstatisztikákat, például a hasznos adatok méretét és időtartamát. (mindig gyűjtik, éles rendszerekben használható.)

• DiagnosticNode: Egy faszerű struktúra, amely részletes diagnosztikai információkat rögzít. Hasonló a böngészőkben har felvételhez. Ez a funkció alapértelmezés szerint le van tiltva, és csak nem éles környezetek hibakeresésére szolgál. (diagnosztikai szinten gyűjtött hibakeresés és hibakeresés nem biztonságos)

• ClientConfig: Az ügyfél konfigurációs beállításaival kapcsolatos alapvető információkat rögzíti az ügyfél inicializálása során. (diagnosztikai szinten gyűjtött hibakeresés és hibakeresés nem biztonságos)

Ügyeljen arra, hogy soha ne állítsa a diagnosztikai szintet debug-unsafe éles környezetben, mivel ez a szint CosmosDiagnostics rögzíti a kérések és válaszok hasznos adatait, és ha úgy dönt, hogy naplózza (alapértelmezés szerint @azure/logger naplózza verbose szinten). Ezek a hasznos adatok rögzítve lehetnek a naplós fogadókban.

Diagnosztika felhasználása

• Mivel diagnostics az összes válaszobjektumhoz hozzáadva. Az alábbiak szerint programozott módon érheti el a CosmosDiagnostic.

import {
  CosmosClient,
  CosmosDbDiagnosticLevel,
  OperationInput,
  BulkOperationType,
} from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({
  endpoint,
  key,
  diagnosticLevel: CosmosDbDiagnosticLevel.debug,
});

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
// For point look up operations

const { container, diagnostics: containerCreateDiagnostic } =
  await database.containers.createIfNotExists({
    id: "<container-id>",
    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;
}

• A diagnostics@azure/loggerhasználatával is naplózhatja, a diagnosztikát mindig @azure/logger naplózza verbose szinten. Ha tehát a diagnosztikai szintet debug vagy debug-unsafe, és @azure/logger szintet verboseértékre állítja, a rendszer naplózza diagnostics.

Következő lépések

További mintakód

több minta elérhető az SDK GitHub tárolójában. Ezek a minták a Cosmos DB használata során gyakran előforduló további forgatókönyvekhez nyújtanak példakódot:

• Adatbázis-műveletek
• Tárolóműveletek
• Elemműveletek
• Indexelés konfigurálása
• Tároló változáscsatorna olvasása
• Tárolt eljárások
• Adatbázis-/tároló átviteli sebesség beállításainak módosítása
• Többrégiós írási műveletek

Korlátozások

Az alábbi funkciók jelenleg nem támogatottak . Alternatív lehetőségekért tekintse meg az alábbi kerülő megoldásokat szakaszt.

• Az ügyféloldali titkosítás jelenleg nem támogatott böngészőkörnyezetben.

Adatsík korlátozásai:

• A COUNT függvényt tartalmazó lekérdezések EGY DISTINCT-alqueryből
• Közvetlen TCP-mód elérése
• A partíciók közötti lekérdezések ( például rendezés, számlálás és különböző elemek) összesítése nem támogatja a folytatási jogkivonatokat. Streamelhető lekérdezések, például SELECT * FROM WHERE <feltétel,> támogatja a folytatási jogkivonatokat. A nem streamelhető lekérdezések folytatási jogkivonat nélkül történő végrehajtásához tekintse meg a "Kerülő megoldás" szakaszt.
• Változáscsatorna: Processzor
• Változáscsatorna: Több partíció kulcsértékének olvasása
• Keresztpartíciós ORDER BY vegyes típusok esetén
• Javasoljuk, hogy frissítsd a legújabb SDK-t, hogy folytató tokeneket használj az oldalozáshoz. Ha folytatási tokeneket használsz keresztpartíciós enableQueryControl lekérdezésekkel (több partíciót átvizsgáló lekérdezésekkel), győződj meg róla, hogy beállítsd forceQueryPlan: true a lekérdezési opciókat determinisztikus végrehajtási terv érvényesítéséhez. Enélkül a lekérdezés végrehajtási viselkedése partíciókon eltérhet, ami befolyásolja a folytatási token konzisztenciáját.

Vezérlősík korlátozásai:

• CollectionSizeUsage, DatabaseUsage és DocumentUsage metrikák lekérése
• Térinformatikai index létrehozása
• Automatikus skálázás átviteli sebességének frissítése

Áthidaló megoldások

Folytatási token a keresztpartíciókhoz, lekérdezések régebbi verziókhoz (< 4.9.0)

A 4.9.0 előtti régebbi verzióknál a folytatási token támogatással lehet keresztpartíciós lekérdezéseket elérni side car pattern használatával. Ez a minta azt is lehetővé teszi, hogy az alkalmazások heterogén összetevőkből és technológiákból álljanak.

Nem streamelhető partíciók közötti lekérdezés végrehajtása

Ha nem streamelhető lekérdezéseket szeretne végrehajtani a folytatási jogkivonatok használata nélkül, létrehozhat egy lekérdezési iterátort a szükséges lekérdezési specifikációval és beállításokkal. Az alábbi mintakód bemutatja, hogyan használható lekérdezési iterátor az összes eredmény lekérésére folytatási jogkivonat nélkül:

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const querySpec = {
  query: "SELECT c.status, COUNT(c.id) AS count FROM c GROUP BY c.status",
};
const queryOptions = {
  maxItemCount: 10, // maximum number of items to return per page
  enableCrossPartitionQuery: true,
};
const queryIterator = container.items.query(querySpec, queryOptions);
while (queryIterator.hasMoreResults()) {
  const { resources: result } = await queryIterator.fetchNext();
  // process results
}

Ez a módszer streamelhető lekérdezésekhez is használható.

Vezérlősík műveletei

Általában a Azure Portal, Azure Cosmos DB Resource Provider REST API, Azure CLI vagy PowerShell használhatók a vezérlősík nem támogatott korlátozásai miatt.

További dokumentáció

A Cosmos DB szolgáltatásról szóló részletesebb dokumentációért lásd a Azure Cosmos DB dokumentációt a learn.microsoft.com-ről.

Hasznos hivatkozások

• Üdvözlünk a Azure Cosmos DB
• gyors üzembe helyezési
• oktatóanyag
• Samples
• Bevezetés a Azure Cosmos DB szolgáltatás erőforrás-modelljébe
• Bevezetés az SQL API of Azure Cosmos DB Service
• particionálási
• API dokumentációs

Hozzájárulás

Ha szeretnél hozzájárulni ehhez a könyvtárhoz, kérjük, olvasd el a hozzájárulás útmutatót hogy többet megtudj arról, hogyan lehet elkészíteni és tesztelni a kódot.