Klientská knihovna Azure Cosmos DB pro JavaScript – verze 4.0.0
/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áteid
, 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í ChangeFeedPullModelIterator
musí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 vyvolatCredentialUnavailableError
.
Následuje příklad zpracování chyb typu ErrorResponse
, TimeoutError
, AbortError
a 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řistupovatCosmosDiagnostic
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
naverbose
úrovni . Pokud tedy nastavíte Úroveň diagnostiky nadebug
hodnotu nebodebug-unsafe
a@azure/logger
úroveň naverbose
hodnotu ,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
- Získání metrik CollectionSizeUsage, DatabaseUsage a DocumentUsage
- Vytvoření geoprostorových indexů
- Aktualizace propustnosti automatického škálování
Omezení řídicí roviny:
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
- Vítá vás Azure Cosmos DB
- Rychlý start
- Kurz
- ukázky
- Úvod do modelu prostředků služby Azure Cosmos DB
- Úvod do rozhraní SQL API služby Azure Cosmos DB
- Dělení
- Dokumentace k rozhraní API
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.
Azure SDK for JavaScript
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro