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

Azure Cosmos DB-ügyfélkódtár JavaScripthez – 4.2.0-s verzió

  • Cikk

/TypeScript

legújabb npm-jelvény buildállapot-

Az Azure Cosmos DB egy globálisan elosztott, többmodelles adatbázis-szolgáltatás, amely támogatja a dokumentum-, kulcs-érték-, széles oszlop- és gráfadatbá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:

Kezdetekhez

Előfeltételek

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

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

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

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

Vagy létrehozhat egy fiókot az 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 az Azure Portal vagy az alábbi Azure CLI--kódrészletet használhatja. 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

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

Éles környezetben a kulcsokhoz hasonló titkos 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. Adatbázis létrehozásakor meg kell adnia a dokumentumok kezelésekor használni kívánt API-t: 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ó 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 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.

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

Tároló létrehozása

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

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 is 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 Items.upsert. Az Azure Cosmos DB szolgáltatáshoz minden elemhez id kulcs szükséges. 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

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.

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

Hierarchikus partíciókulcsú elem lekérdezése 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

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

// 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:

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ása a paramétereket és értékeiket tartalmazó objektum 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 `);
}

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é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 ChangeFeedIteratorOptionsmaxItemCount 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
// 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 a 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 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.

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

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

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.

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 úgy lettek kialakítva, hogy támogassák az ES5 JavaScript szintaxisát és Node.jsLTS-verzióit. Ha segítségre 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 fordítania az SDK-kódot.

Á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 @azure/loggersetLogLevel 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.

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óit.

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

Az SDK GitHub-adattárában több minta érhető el. 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.

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 , 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" szakaszt.
  • Változáscsatorna: Processzor
  • Változáscsatorna: Több partíció kulcsértékének olvasása
  • 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

    Áthidaló megoldások

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

    A particionálások közötti lekérdezéseket a folytatási jogkivonat támogatásával érheti el Oldalsó autó mintahaszná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 stremable keresztpartíciós 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:

    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 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űveletei

    Általában Azure Portal, Azure Cosmos DB resource provider REST API, Azure CLI vagy PowerShell- használhatja a vezérlősík nem támogatott korlátozásaihoz.

    További dokumentáció

    A Cosmos DB szolgáltatással kapcsolatos részletesebb dokumentációért tekintse meg Azure Cosmos DB dokumentációját a docs.microsoft.com.

    Hozzájárulá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.

    benyomások