Klientská knihovna Azure Cosmos DB pro JavaScript – verze 4.0.0

Článek
09/13/2023

/Stroji

Azure Cosmos DB je globálně distribuovaná a databázová služba pro více modelů, která dokumentační databáze, databáze typu klíč-hodnota, databáze širokých sloupců a databáze grafů. Tento balíček je určený pro aplikace v JavaScriptu nebo TypeScriptu pro interakci s databázemi rozhraní SQL API a dokumenty JSON, které obsahují:

Vytvář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 (dokumentů JSON) v kontejnerech
Dotazování dokumentů v databázi pomocí syntaxe podobné SQL

Klíčové odkazy:

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é Azure a účet služby Cosmos DB (rozhraní SQL API).

Pokud potřebujete účet rozhraní SQL API služby Cosmos DB, můžete ho vytvořit pomocí Cloud Shell Azure 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. Měli byste používat Node verze 10 nebo vyšší.

CORS

Pokud potřebujete vyvíjet pro prohlížeče, musíte pro svůj účet Cosmos DB nastavit pravidla sdílení prostředků mezi zdroji (CORS ). 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 aklíč účtu služby Cosmos DB. 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 jsou klíče, měly ukládat v Azure Key Vault

Klíčové koncepty

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

Databáze: Účet 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 práci s jejími dokumenty: SQL, MongoDB, Gremlin, Cassandra nebo Azure Table. Ke správě kontejnerů použijte databázový objekt .
Kontejner: Kontejner je kolekce dokumentů JSON. Položky v kontejneru můžete vytvářet (vkládat), čí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 id klíč s hodnotou, která jednoznačně identifikuje položku v rámci kontejneru. Pokud nezadáte id, sada SDK ho vygeneruje automaticky.

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 Cosmos DB, mezi které patří:

Vytvoření databáze
Vytvoření kontejneru
Použití klíčů oddílů
Vložit položky
Dotazování na dokumenty
Čtení položky
Odstranění položky
CRUD v kontejneru s klíčem hierarchického oddílu

Vytvoření databáze

Po ověření klienta 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 buď jako hodnota literálu, nebo jako 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ěl by být zadán 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žit položky

Chcete-li vložit položky do kontejneru, předejte objekt obsahující vaše data do souboru Items.upsert. Služba Azure Cosmos DB vyžaduje, aby každá položka má klíč id . 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

Ke čtení jedné položky z kontejneru použijte Item.read. Jedná se o levnější operaci než dotazování pomocí SQL.id

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

CRUD v kontejneru s klíčem hierarchického oddílu

Vytvoření kontejneru s klíčem hierarchického 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 klíčem hierarchického 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();

Dotaz na položku 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

Pokud chcete 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 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 hodnoty 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.

Pokud chcete kanál změn zpracovat, vytvořte instanci .ChangeFeedPullModelIterator Při počátečním vytváření ChangeFeedPullModelIteratormusíte zadat požadovanou changeFeedStartFrom hodnotu uvnitř objektu 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 změny mají načíst. Volitelně můžete použít maxItemCount in ChangeFeedIteratorOptions a nastavit maximální počet položek přijatých na stránku.

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

Existují čtyři výchozí 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
}

Vzhledem k tomu, že kanál změn je vlastně nekonečný seznam položek, který zahrnuje 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 tady.

Zpracování chyb

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

ErrorResponse vyvolá se, pokud odpověď operace vrátí kód >chyby =400.
TimeoutError vyvolá se, pokud se interně volá přerušení kvůli vypršení časového limitu.
AbortError je vyvolán, pokud přerušení způsobil nějaký uživatel předaný signál.
RestError vyvolá se v případě selhání základního systémového volání kvůli problémům se sítí.
Chyby generované libovolnými devDependencies. Např. @azure/identity balíček 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.
  }
}

Tyto chyby je důležité správně zpracovat, abyste zajistili, že se vaše aplikace bude moct bez problémů zotavit z jakýchkoli selhání a dál fungovat podle očekávání. Další podrobnosti o některých z těchto chyb a jejich možných řešeních najdete tady.

Poradce při potížích

Obecné

Když pracujete s chybami služby Cosmos DB vrácené službou, odpovídají stejným stavovým kódům HTTP vráceným pro požadavky rozhraní REST API:

Stavové kódy HTTP pro službu Azure Cosmos DB

Konflikty

Pokud se například pokusíte vytvořit položku pomocí id položky, která se už používá ve vaší databázi Cosmos DB, 409 vrátí se chyba označující konflikt. V následujícím fragmentu kódu se chyba elegantně zpracuje 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");
  }
}

Transpilace

Sady Azure SDK jsou navržené tak, aby podporovaly javascriptovou syntaxi ES5 a verze LTS Node.js. Pokud potřebujete podporu pro starší moduly runtime JavaScriptu, jako je Internet Explorer nebo Node 6, budete muset transpilovat kód sady SDK 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ůžete narazit na přechodná selhání způsobená omezeními přenosové 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 Model opakování v průvodci Vzory návrhu cloudu a souvisejícím vzorem Jistič.

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v @azure/logger. Při používání AZURE_LOG_LEVEL se ujistěte, že jste ho nastavili před inicializaci knihovny protokolování. V ideálním případě ho předejte přes příkazový řádek, pokud používáte knihovny, jako je například dotenv , ujistěte se, že jsou tyto knihovny inicializovány před knihovnou protokolování.

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

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k balíčkům @azure/protokolovacího nástroje.

Diagnostika

Funkce Diagnostiky cosmos poskytuje rozšířené přehledy o všech operacích klienta. Do odpovědi na všechny operace klienta se přidá objekt CosmosDiagnostics. Například

Opakování operace vyhledání bodu – item.read(), , container.create()database.delete()
Opakování operace dotazu -queryIterator.fetchAll(),
Hromadné a dávkové operace -item.batch().
Objekty odpovědí na chyby nebo výjimky.

Do odpovědi na všechny operace klienta se přidá objekt CosmosDiagnostics. K dispozici jsou 3 úrovně diagnostiky cosmos, informace, ladění a ladění – nebezpečné. Pokud jsou pro produkční systémy určeny pouze informace, při vývoji a ladění se používají pouze informace a při ladění, protože tyto systémy spotřebovávají výrazně více prostředků. Úroveň diagnostiky služby Cosmos Db můžete 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 než nastavení prostřednictvím možností klienta.)

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Cosmos Diagnostic má tři členy

Typ ClientSideRequestStatistics: Obsahuje agregované diagnostické podrobnosti, včetně vyhledávání metadat, opakovaných pokusů, kontaktovaných koncových bodů a statistik požadavků a odpovědí, jako je velikost datové části a doba trvání. (shromažďuje se vždy, může být použit v produkčních systémech.)
DiagnosticNode: Stromová struktura, která zachycuje podrobné diagnostické informace. Podobá se záznamu har v prohlížečích. Tato funkce je ve výchozím nastavení zakázaná a je určená pouze pro ladění neprodukční prostředí. (shromažďováno na úrovni ladění a nebezpečné ladění na úrovni diagnostiky)
ClientConfig: Zachytává základní informace související s nastavením konfigurace klienta během inicializace klienta. (shromažďováno na úrovni ladění a nebezpečné ladění na úrovni diagnostiky)

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

Využívání diagnostiky

Protože diagnostics se přidá do všech objektů Response. Můžete programově přistupovat CosmosDiagnostic 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/loggerDiagnostika se vždy protokoluje pomocí @azure/logger na verbose úrovni . Pokud tedy nastavíte Úroveň diagnostiky na debug hodnotu nebo debug-unsafe a @azure/logger úroveň na verbosehodnotu , diagnostics budou se protokolovat.

Další kroky

Další vzorový kód

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

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ě nejsou podporovány následující funkce. Alternativní možnosti najdete níže v části Alternativní řešení .

Omezení roviny dat:

Dotazy s počtem z poddotazů DISTINCT
Přímý přístup v režimu TCP
Agregované dotazy napříč oddíly, jako je řazení, počítání a distinct, nepodporují tokeny pokračování. Dotazy, které lze streamovat, například SELECT * FROM WHERE podporují tokeny pro pokračování. V části Alternativní řešení najdete informace o spouštění nestreamovatelných dotazů bez tokenu pro pokračování.
Kanál změn: Procesor
Kanál změn: Čtení hodnot klíčů několika oddílů
Model vyžádání kanálu změn – všechny verze a režim odstranění #27058
Podpora modelu vyžádá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í

Pokračovací token pro dotazy napříč oddíly

Dotazy napříč oddíly můžete dosáhnout s podporou tokenů pro pokračování pomocí modelu Boční auto. S tímto modelem také může být možné vytváření aplikací z heterogenních komponent a technologií.

Provádění nerušitelného dotazu napříč oddíly

Pokud chcete spouštět dotazy, které nelze streamovat, bez použití pokračovacích tokenů, můžete vytvořit iterátor dotazů 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 pro pokračování:

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
}

Tento přístup lze použít také pro dotazy, které lze streamovat.

Operace řídicí roviny

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

Další dokumentace

Podrobnější dokumentaci ke službě Cosmos DB najdete v dokumentaci ke službě Azure Cosmos DB týkající se docs.microsoft.com.

Užitečné odkazy

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

Imprese

Sdílet prostřednictvím