Megosztás a következőn keresztül:

JavaScripthez készült Azure Cosmos DB ügyfélkódtár – 4.0.0-s verzió

  • Cikk

/TypeScript

legújabb npm jelvénybuildállapota

Az Azure Cosmos DB egy globálisan elosztott, többmodelles adatbázis-szolgáltatás, amely dokumentum és kulcs–érték típusú, valamint széles oszlopú és gráfadatbázisokat támogat. Ez a csomag JavaScript-/TypeScript-alkalmazások számára készült az SQL API-adatbázisok és az általuk tartalmazott JSON-dokumentumok használatá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:

Első lépések

Előfeltételek

Azure-előfizetés és Cosmos DB SQL API-fiók

A csomag használatához Azure-előfizetéssel és Cosmos DB-fiókkal (SQL API) kell rendelkeznie.

Ha Cosmos DB SQL API-fiókra van szüksége, az Azure Cloud Shell használatával létrehozhat egyet az Alábbi Azure CLI-paranccsal:

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

Vagy létrehozhat egy fiókot az Azure Portalon

NodeJS

Ez a csomag az npm-en keresztül van elosztva, amely a NodeJS-sel előre telepítve van. A Node v10-et vagy újabb verziót kell használnia.

CORS

Ha böngészőkhöz kell fejlesztenie, be kell állítania az eltérő eredetű erőforrások megosztására (CORS) vonatkozó 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ók végpontjára és kulcsára. Ezeket megtalálhatja az Azure Portalon , vagy használhatja az alábbi Azure CLI-kódrészletet . A kódrészlet a Bash-felülethez 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

Példány létrehozása CosmosClient

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

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

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

Éles környezetben a titkos kulcsokat, például a kulcsokat az Azure-ban kell tárolni, Key Vault

Fő fogalmak

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

  • Adatbázis: A Cosmos DB-fiókok több adatbázist is tartalmazhatnak. Adatbázis létrehozásakor meg kell adnia azt az API-t, amelyet használni szeretne a dokumentumaival való interakcióhoz: SQL, MongoDB, Gremlin, Cassandra vagy Azure Table. Használja az Adatbázis objektumot a tárolók kezeléséhez.

  • Tároló: A tároló JSON-dokumentumok gyűjteménye. A Tároló objektum metódusainak használatával elemeket hozhat létre (szúrhat be), olvashat, frissíthet és törölhet egy tárolóban .

  • 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 , idaz SDK automatikusan létrehoz egyet.

További információ ezekről az erőforrásokról: Az Azure Cosmos-adatbázisok, -tárolók és -elemek használata.

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

A CosmosClient hitelesí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.

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

Tároló létrehozása

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

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

Partíciókulcsok használata

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

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 adható meg.

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.

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 az Items.upsert fájlnak. Az Azure Cosmos DB szolgáltatáshoz minden elemnek rendelkeznie kell egy id kulccsal. Ha nem ad meg egyet, az SDK automatikusan létrehoz egy értéket id .

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

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 az Item.read parancsot. Ez egy kevésbé költséges művelet, mint az SQL használata a lekérdezéséhez.id

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

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

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

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

Elem beszúrása a következőként definiált hierarchikus partíciókulccsal: ["/name", "/address/zip"]

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"],

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

Elem lekérdezése hierarchikus partíciókulccsal a következőként definiált hierarchikus partíciókulccsal: ["/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} `);
}

Elem törlése

Elemek tárolóból való törléséhez használja az Item.delete parancsot.

// 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ázisok támogatják a tároló elemeinek az Items.query használatával történő lekérdezését SQL-szerű szintaxissal:

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

Paraméteres lekérdezések végrehajtásához adjon át egy objektumot, amely tartalmazza a paramétereket és azok értékeit az Items.querynek:

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

További információ a Cosmos DB-adatbázisok SQL API-val történő lekérdezéséről: Azure Cosmos DB-adatok lekérdezése SQL-lekérdezésekkel.

Változáscsatorna lekérési 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 példányt a következőből ChangeFeedPullModelIterator: . A létrehozásakor ChangeFeedPullModelIteratormeg kell adnia egy kötelező changeFeedStartFrom értéket a ChangeFeedIteratorOptions fájlon belül, amely a módosítások olvasásának kezdőpozícióját és azt az erőforrást (partíciókulcsot vagy FeedRange-t) tartalmazza, amelyhez a módosításokat le kell kérni. A(z) használatával megadhatja maxItemCountChangeFeedIteratorOptions az egy oldalonként fogadott elemek maximális számát.

Megjegyzés: Ha nincs changeFeedStartFrom megadva érték, akkor a changefeed egy teljes tárolóra lesz lekérve a Now() fájlból.

A változáscsatornának négy kezdőpozíciója van:

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

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

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 értéke hasMoreResults mindig true. Amikor megpróbálja elolvasni a változáscsatornát, és nincsenek elérhető új módosítások, állapotú NotModified választ kap.

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

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 lesz eldobva, ha a megszakítást időtúllépés miatt belsőleg hívják meg.
  3. AbortError akkor lesz eldobva, ha a felhasználó által átadott jel okozta a megszakítást.
  4. RestError a rendszer a mögöttes rendszerhívás hálózati problémák miatti hibája esetén jelenik meg.
  5. A devDependencies által létrehozott hibák. Például: @azure/identity csomag dobhat CredentialUnavailableError.

Az alábbi példa a , , TimeoutErrorAbortErrorés RestErrortípusú ErrorResponsehibák kezelésére mutat be példát.

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 továbbra is a várt módon működjön. Ezekről a hibákról és azok lehetséges megoldásairól itt talál további információt.

Hibaelhárítás

Általános kérdések

Amikor a szolgáltatás által visszaadott Cosmos DB-hibákkal kommunikál, ugyanazoknak a HTTP-állapotkódoknak felelnek meg, amelyeket a REST API-kérések esetében ad vissza:

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

Ütközések

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

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

Fordítás

Az Azure SDK-k a Node.jsES5 JavaScript-szintaxisát és LTS-verzióit támogatják. Ha támogatásra van szüksége a korábbi JavaScript-futtatókörnyezetekhez, például az Internet Explorerhez vagy a Node 6-hoz, a buildelési folyamat részeként át kell lefordítania az SDK-kódot.

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

A Cosmos DB használata során átmeneti hibákat tapasztalhat, amelyeket a szolgáltatás által kényszerített sebességkorlátok vagy más átmeneti problémák, például a hálózati kimaradások okoznak. Az ilyen típusú hibák kezelésével kapcsolatos információkért lásd: Újrapróbálkozási minta a felhőtervezési minták útmutatójában és a kapcsolódó áramkör-megszakító minta.

Naplózá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 környezeti változót a AZURE_LOG_LEVEL értékre info. A naplózás futásidőben is engedélyezhető, ha setLogLevel meghívja a következőt: @azure/logger. A használat AZURE_LOG_LEVEL során győződjön meg arról, hogy be van állítva a naplózási kódtár inicializálása előtt. Ideális esetben adja át a parancssoron keresztül, ha kódtárakat használ, például dotenv ellenőrizze, hogy az ilyen kódtárak inicializálva vannak-e a naplózás előtt.

const { setLogLevel } = require("@azure/logger");
setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációt.

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

  • Pontkeresési művelet reponse – item.read(), , container.create()database.delete()
  • Lekérdezési művelet reponse -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 szánt 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 magasabb erőforrásokat használnak fel. A Cosmos diagnosztikai szintje kétféleképpen állítható be

  • Programozott módon
  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, mint az ügyfélbeállításokon keresztüli beállítás.)
  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

A Cosmos Diagnostic három tagból áll

  • ClientSideRequestStatistics Típusa: Ö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: Faszerű szerkezet, amely részletes diagnosztikai információkat rögzít. Hasonló a har böngészőkben található 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 nem biztonságos hibakeresés)

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

Győződjön meg arról, hogy soha nem állítja be 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 a szint naplózza @azure/loggerverbose ). Ezek a hasznos adatok rögzítve lehetnek a naplós fogadókban.

Diagnosztika felhasználása

  • Mivel diagnostics az összes válaszobjektumhoz hozzá van adva. Az alábbiak szerint programozott módon férhet hozzá CosmosDiagnostic .
  // 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
  }
  • A használatával is bejelentkezhet@azure/loggerdiagnostics, a diagnosztikát mindig a szinten verbose naplózza a rendszer@azure/logger. Ha tehát a diagnosztikai szintet a vagy debug-unsafe@azure/logger értékre debugverbosediagnostics állítja, a rendszer naplózza.

Következő lépések

További mintakód

Az SDK GitHub-adattárában számos minta érhető el. Ezek a minták példakódot biztosítanak a Cosmos DB használata során gyakran előforduló további forgatókönyvekhez:

  • 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ások szakaszt.

Adatsíkra vonatkozó korlátozások:

  • A COUNT függvénnyel rendelkező lekérdezések EGY DISTINCT-albekérdezésből
  • Közvetlen TCP-mód elérése
  • A partíciók közötti lekérdezések , például a rendezés, a számolás és a 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 , a folytatási jogkivonatok támogatása. 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" című szakaszt.
  • Változáscsatorna: Processzor
  • Változáscsatorna: Több partíció kulcsértékeinek olvasása
  • Változáscsatorna lekérési modell minden verziója és törlési mód #27058
  • Változáscsatorna lekéréses modell támogatása részleges hierarchikus partíciókulcsokhoz #27059
  • Keresztpartíciós ORDER BY vegyes típusok esetén

    • 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

    Kerülő megoldások

    Folytatási jogkivonat partíciók közötti lekérdezésekhez

    A particionálások közötti lekérdezéseket folytatási jogkivonat-támogatással, side car minta használatával érheti el. Ez a minta azt is lehetővé teheti, hogy az alkalmazások heterogén összetevőkből és technológiákból álljanak.

    Nem stremable keresztpartíciós lekérdezés végrehajtása

    Ha folytatási jogkivonatok használata nélkül szeretne nem streamelhető lekérdezéseket végrehajtani, 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átort az összes eredmény lekéréséhez folytatási jogkivonat nélkül:

    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
}

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

    Vezérlősík-műveletek

    A vezérlősík nem támogatott korlátaihoz általában az Azure Portalt, az Azure Cosmos DB erőforrás-szolgáltató RESTAPI-t, az Azure CLI-t vagy a PowerShellt használhatja.

    További dokumentáció

    A Cosmos DB szolgáltatás részletesebb dokumentációját az Azure Cosmos DB dokumentációjában találja a docs.microsoft.com.

    Közreműködés

    Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót , amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

    Megjelenések