Klientská knihovna Azure Cosmos DB pro JavaScript – verze 4.2.0

Článek
11/20/2024

/Strojopis

Azure Cosmos DB je globálně distribuovaná databázová služba s více modely, která podporuje databáze dokumentů, klíč-hodnota, široký sloupec a grafové databáze. Tento balíček je určený pro aplikace JavaScript/TypeScript pro interakci s databázemi rozhraní SQL API a dokumenty JSON, které obsahují:

Vytvoření databází Cosmos DB a úprava jejich nastavení
Vytváření a úpravy kontejnerů pro ukládání kolekcí dokumentů JSON
Vytváření, čtení, aktualizace a odstraňování položek (dokumenty JSON) v kontejnerech
Dotazování dokumentů v databázi pomocí syntaxe podobné SQL

Klíčové odkazy:

balíčku (npm)
Referenční dokumentace k rozhraní API
dokumentace k produktu

Začínáme

Požadavky

Předplatné Azure a účet rozhraní SQL API služby Cosmos DB

Abyste mohli tento balíček používat, musíte mít předplatné Azurea účet služby Cosmos DB (SQL API).

Pokud potřebujete účet rozhraní SQL API služby Cosmos DB, můžete ho pomocí azure Cloud Shellu vytvořit pomocí tohoto příkazu Azure CLI:

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

Nebo můžete vytvořit účet na webu Azure Portal

NodeJS

Tento balíček se distribuuje prostřednictvím npm, který je předinstalovaný s NodeJS pomocí verze LTS.

CORS

Pokud potřebujete vyvíjet prohlížeče, musíte pro svůj účet Cosmos DB nastavit sdílení prostředků mezi zdroji (CORS) pravidla. Podle pokynů v propojeném dokumentu vytvořte nová pravidla CORS pro službu Cosmos DB.

Nainstalovat tento balíček

npm install @azure/cosmos

Získání přihlašovacích údajů účtu

Budete potřebovat koncový bod účtu služby Cosmos DB a klíč. Najdete je na webu Azure Portal nebo použijte fragment kódu Azure CLI níže. Fragment kódu je naformátovaný pro prostředí Bash.

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

Vytvoření instance `CosmosClient`

Interakce se službou Cosmos DB začíná instancí třídy CosmosClient

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

Pro zjednodušení jsme zahrnuli key a endpoint přímo do kódu, ale pravděpodobně je budete chtít načíst ze souboru, který není ve správě zdrojového kódu, pomocí projektu, jako je dotenv nebo načítání z proměnných prostředí.

V produkčních prostředích by se tajné kódy jako klíče měly ukládat ve službě azure Key Vault

Klíčové koncepty

Po inicializaci CosmosClient můžete pracovat s primárními typy prostředků ve službě Cosmos DB:

databáze: Účet služby Cosmos DB může obsahovat více databází. Při vytváření databáze zadáte rozhraní API, které chcete použít při interakci s jeho dokumenty: SQL, MongoDB, Gremlin, Cassandra nebo Azure Table. Ke správě kontejnerů použijte objekt Database.
kontejner: Kontejner je kolekce dokumentů JSON. Položky v kontejneru můžete vytvářet (vložit), číst, aktualizovat a odstraňovat pomocí metod v objektu Container.
Položka: Položka je dokument JSON uložený v kontejneru. Každá položka musí obsahovat klíč id s hodnotou, která jedinečně identifikuje položku v kontejneru. Pokud nezadáte id, sada SDK ho automaticky vygeneruje.

Další informace o těchto prostředcích najdete v tématu Práce s databázemi, kontejnery a položkami Azure Cosmos.

Příklady

Následující části obsahují několik fragmentů kódu, které pokrývají některé z nejběžnějších úloh služby Cosmos DB, mezi které patří:

Vytvoření databáze
Vytvoření kontejneru
použití klíčů oddílů
Vložit položky
dotazování dokumentů
Čtení položky
Odstranění položky
CRUD v kontejneru s hierarchickým klíčem oddílu

Vytvoření databáze

Po ověření CosmosClient můžete pracovat s libovolným prostředkem v účtu. Následující fragment kódu vytvoří databázi rozhraní API NOSQL.

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

Vytvoření kontejneru

Tento příklad vytvoří kontejner s výchozím nastavením.

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

Použití klíčů oddílů

Tento příklad ukazuje různé typy podporovaných klíčů oddílů.

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

Pokud se klíč oddílu skládá z jedné hodnoty, může být zadán jako hodnota literálu nebo pole.

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

Pokud se klíč oddílu skládá z více než jedné hodnoty, měla by být zadána jako pole.

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

Vložení položek

Chcete-li vložit položky do kontejneru, předejte objekt obsahující vaše data Items.upsert. Služba Azure Cosmos DB vyžaduje, aby každá položka byla id klíč. Pokud ho nezadáte, sada SDK automaticky vygeneruje id.

Tento příklad vloží do kontejneru několik položek.

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

Čtení položky

Pokud chcete přečíst jednu položku z kontejneru, použijte Item.read. Jedná se o levnější operaci než použití SQL k dotazování pomocí id.

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

CRUD v kontejneru s hierarchickým klíčem oddílu

Vytvoření kontejneru s hierarchickým klíčem oddílu

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

Vložení položky s hierarchickým klíčem oddílu definovaným jako – ["/name", "/address/zip"]

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

Čtení jedné položky z kontejneru s hierarchickým klíčem oddílu definovaným jako – ["/name", "/address/zip"],

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

Dotazování položky s hierarchickým klíčem oddílu s hierarchickým klíčem oddílu definovaným jako – ["/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} `);
}

Odstranění položky

Chcete-li odstranit položky z kontejneru, použijte Item.delete.

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

Dotazování databáze

Databáze rozhraní SQL API služby Cosmos DB podporuje dotazování položek v kontejneru pomocí Items.query pomocí syntaxe podobné SQL:

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

Proveďte parametrizované dotazy předáním objektu obsahujícího parametry a jejich hodnot do 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 `);
}

Další informace o dotazování databází Cosmos DB pomocí rozhraní SQL API najdete v tématu Dotazování dat služby Azure Cosmos DB pomocí dotazů SQL.

Model vyžádání kanálu změn

Kanál změn je možné načíst pro klíč oddílu, rozsah kanálu nebo celý kontejner.

Chcete-li zpracovat kanál změn, vytvořte instanci ChangeFeedPullModelIterator. Při počátečním vytvoření ChangeFeedPullModelIteratormusíte zadat požadovanou changeFeedStartFrom hodnotu uvnitř ChangeFeedIteratorOptions, která se skládá z počáteční pozice pro čtení změn a prostředku (klíč oddílu nebo FeedRange), pro které se mají změny načíst. Volitelně můžete použít maxItemCount v ChangeFeedIteratorOptions k nastavení maximálního počtu přijatých položek na stránku.

Poznámka: Pokud není zadána žádná changeFeedStartFrom hodnota, načte se kanál změn pro celý kontejner z Now().

Existují čtyři počáteční pozice pro kanál změn:

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

Tady je příklad načtení kanálu změn pro klíč oddílu.

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
}

Protože kanál změn je v podstatě nekonečný seznam položek, které zahrnují všechny budoucí zápisy a aktualizace, hodnota hasMoreResults je vždy true. Když se pokusíte přečíst kanál změn a nejsou k dispozici žádné nové změny, obdržíte odpověď se stavem NotModified.

Podrobnější pokyny k používání a příklady kanálu změn najdete zde.

Zpracování chyb

Sada SDK generuje různé typy chyb, ke kterým může dojít během operace.

ErrorResponse je vyvolán, pokud odpověď operace vrátí kód chyby >=400.
TimeoutError je vyvolána, pokud se přeruší interně kvůli vypršení časového limitu.
AbortError je vyvolán, pokud některý uživatel předal signál, který způsobil přerušení.
RestError je vyvolán v případě selhání základního volání systému kvůli problémům se sítí.
Chyby vygenerované všemi devDependencies Např. balíček @azure/identity může vyvolat CredentialUnavailableError.

Následuje příklad zpracování chyb typu ErrorResponse, TimeoutError, AbortErrora 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.
  }
}

Je důležité správně zpracovávat tyto chyby, aby se zajistilo, že se vaše aplikace může řádně zotavit z jakýchkoli selhání a pokračovat v fungování podle očekávání. Další podrobnosti o některých z těchto chyb a jejich možných řešení najdete zde.

Řešení problémů

Obecné

Při interakci s chybami služby Cosmos DB vrácenými službou odpovídají stejným stavovým kódům HTTP vráceným pro požadavky rozhraní REST API:

stavových kódů HTTP pro službu Azure Cosmos DB

Konflikty

Pokud se například pokusíte vytvořit položku pomocí id, která se už používá v databázi Cosmos DB, vrátí se chyba 409 označující konflikt. V následujícím fragmentu kódu je chyba zpracována elegantně zachycením výjimky a zobrazením dalších informací o chybě.

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

Transpilování

Sady Azure SDK jsou navržené tak, aby podporovaly syntaxi ES5 JavaScript a LTS verze Node.js. Pokud potřebujete podporu pro starší moduly runtime JavaScriptu, jako je Internet Explorer nebo Node 6, budete muset kód sady SDK transpilovat jako součást procesu sestavení.

Zpracování přechodných chyb s opakováním

Při práci se službou Cosmos DB může docházet k přechodným selháním způsobeným limity rychlosti vynucenými službou nebo jinými přechodnými problémy, jako jsou výpadky sítě. Informace o zpracování těchto typů selhání najdete v tématu vzor opakování v průvodci vzory návrhu cloudu a související vzor jističe jistič.

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Protokolování lze také povolit za běhu voláním setLogLevel v @azure/logger. Při použití AZURE_LOG_LEVEL před inicializacem knihovny protokolování se ujistěte, že je nastavená. Pokud používáte knihovny jako dotenv před protokolováním knihovny inicializovat tyto knihovny, v ideálním případě ho projděte příkazovým řádkem.

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

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Diagnostika

Funkce Diagnostiky služby Cosmos poskytuje rozšířené přehledy o všech operacích klienta. Do odpovědi všech klientských operací se přidá objekt CosmosDiagnostics. například

Reonování operací vyhledávání bodů – item.read(), container.create(), database.delete()
Reponse operace dotazu –queryIterator.fetchAll(),
Hromadné a dávkové operace –item.batch().
Objekty odpovědi na chybu nebo výjimku

Do odpovědi všech klientských operací se přidá objekt CosmosDiagnostics. K dispozici jsou 3 úrovně diagnostiky Služby Cosmos DB, informace, ladění a ladění. Pokud jsou určené pouze informace pro produkční systémy a ladění a jsou nebezpečné pro ladění, mají být použity při vývoji a ladění, protože spotřebovávají výrazně vyšší prostředky. Úroveň diagnostiky služby Cosmos DB je možné nastavit 2 způsoby.

Programově

  const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });

Použití proměnných prostředí (Úroveň diagnostiky nastavená proměnnou prostředí má vyšší prioritu před nastavením prostřednictvím možností klienta.)

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Služba Cosmos Diagnostic má tři členy.

ClientSideRequestStatistics Type: Obsahuje agregované podrobnosti diagnostiky, včetně vyhledávání metadat, opakování, kontaktovaných koncových bodů a statistik požadavků a odpovědí, jako je velikost datové části a doba trvání. (je vždy shromažďován, lze je používat v produkčních systémech.)
DiagnosticNode: Je stromová struktura, která zachycuje podrobné diagnostické informace. Podobně jako har záznam, který se nachází v prohlížečích. Tato funkce je ve výchozím nastavení zakázaná a je určená jenom pro ladění neprodukčního prostředí. (shromážděno na úrovni diagnostiky ladění a nebezpečné ladění)
ClientConfig: Zaznamenává základní informace související s nastavením konfigurace klienta během inicializace klienta. (shromážděno na úrovni diagnostiky ladění a nebezpečné ladění)

Nezapomeňte nikdy nastavit úroveň diagnostiky na debug-unsafe v produkčním prostředí, protože tato úroveň CosmosDiagnostics zaznamenává datové části požadavků a odpovědí a pokud se rozhodnete ji protokolovat (ve výchozím nastavení se protokoluje @azure/logger na úrovni verbose). Tyto datové části se můžou zachytit v jímkách protokolů.

Využívání diagnostiky

Vzhledem k tomu, diagnostics je přidán do všech objektů Response. K CosmosDiagnostic můžete přistupovat programově následujícím způsobem.

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

Můžete také protokolovat diagnostics pomocí @azure/logger, diagnostika se vždy protokoluje pomocí @azure/logger na úrovni verbose. Pokud tedy nastavíte úroveň diagnostiky na debug nebo debug-unsafe a úroveň @azure/logger na verbose, diagnostics se zaprotokoluje.

Další kroky

Další ukázkový kód

v úložišti GitHub sady SDK je k dispozici několik ukázek. Tyto ukázky poskytují ukázkový kód pro další scénáře, ke kterým běžně dochází při práci se službou Cosmos DB:

Databázové operace
Operace s kontejnery
Operace s položkami
Konfigurace indexování
Čtení kanálu změn kontejneru
Uložené procedury
Změna nastavení propustnosti databáze nebo kontejneru
Operace zápisu do více oblastí

Omezení

V současné době se níže uvedené funkce nepodporují. Alternativní možnosti najdete v části Alternativní řešení níže.

Omezení roviny dat:

Dotazy s funkcí COUNT z poddotazu DISTINCT
Přímý přístup k režimu TCP
Agregace dotazů napříč oddíly, jako je řazení, počítání a odlišné, nepodporují tokeny pokračování. Streamovatelné dotazy, jako je SELECT * FROM WHERE , podpora pokračovací tokeny. Informace o provádění nestreamovatelných dotazů bez tokenu pro pokračování najdete v části Alternativní řešení.
Kanál změn: Procesor
Kanál změn: Čtení hodnot klíče více oddílů
Podpora modelu vyžádání změn kanálu změn pro částečné hierarchické klíče oddílů #27059
Order BY napříč oddíly pro smíšené typy

Omezení řídicí roviny:

Získání metrik CollectionSizeUsage, DatabaseUsage a DocumentUsage
Vytvoření geoprostorových indexů
Aktualizace propustnosti automatického škálování

Alternativní řešení

Token pro pokračování pro dotazy napříč oddíly

Dotazy napříč oddíly s podporou tokenů pro pokračování můžete dosáhnout pomocí modeluBoční auto . Tento model může také umožnit, aby se aplikace skládají z heterogenních komponent a technologií.

Provádění neposouvatelného dotazu napříč oddíly

Pokud chcete spouštět nestreamovatelné dotazy bez použití tokenů pokračování, můžete vytvořit iterátor dotazu s požadovanou specifikací a možnostmi dotazu. Následující ukázkový kód ukazuje, jak pomocí iterátoru dotazu načíst všechny výsledky bez nutnosti tokenu pokračování:

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
}

Tento přístup lze použít také pro streamovatelné dotazy.

Operace řídicí roviny

Pro nepodporovaná omezení řídicí roviny obvykle můžete použítwebu Azure Portal, rozhraní REST API poskytovatele prostředků služby Azure Cosmos DB, Azure CLI nebo Power Shellu.

Další dokumentace

Rozsáhlejší dokumentaci ke službě Cosmos DB najdete v dokumentaci ke službě Azure Cosmos DB docs.microsoft.com.

Užitečné odkazy

vítá vás služba Azure Cosmos DB
úvodní
kurz
ukázky
Úvod k modelu prostředků služby Azure Cosmos DB
Úvod do rozhraní SQL API služby Azure Cosmos DB service
dělení
Dokumentace k rozhraní API

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

imprese

Sdílet prostřednictvím