Využití databáze dokumentů Azure Cosmos DB v :::no-loc(Xamarin.Forms):::Consume an Azure Cosmos DB Document Database in :::no-loc(Xamarin.Forms):::

Stažení ukázky stažení ukázkyDownload Sample Download the sample

Azure Cosmos DB databáze dokumentů je databáze NoSQL, která poskytuje přístup s nízkou latencí k dokumentům JSON, nabízí rychlou, vysoce dostupnou a škálovatelnou databázovou službu pro aplikace, které vyžadují bezproblémové škálování a globální replikaci. V tomto článku se dozvíte, jak pomocí klientské knihovny Azure Cosmos DB .NET Standard integrovat do aplikace Azure Cosmos DB databázi dokumentů :::no-loc(Xamarin.Forms)::: .An Azure Cosmos DB document database is a NoSQL database that provides low latency access to JSON documents, offering a fast, highly available, scalable database service for applications that require seamless scale and global replication. This article explains how to use the Azure Cosmos DB .NET Standard client library to integrate an Azure Cosmos DB document database into a :::no-loc(Xamarin.Forms)::: application.

Video Microsoft Azure Cosmos DBMicrosoft Azure Cosmos DB video

Účet databáze dokumentů Azure Cosmos DB se dá zřídit pomocí předplatného Azure.An Azure Cosmos DB document database account can be provisioned using an Azure subscription. Každý databázový účet může mít nula nebo více databází.Each database account can have zero or more databases. Databáze dokumentů v Azure Cosmos DB je logický kontejner pro kolekce dokumentů a uživatele.A document database in Azure Cosmos DB is a logical container for document collections and users.

Databáze dokumentu Azure Cosmos DB může obsahovat nula nebo více kolekcí dokumentů.An Azure Cosmos DB document database may contain zero or more document collections. Každá kolekce dokumentů může mít jinou úroveň výkonu, což umožňuje zadat větší propustnost pro často používané kolekce a menší propustnost pro zřídka používané kolekce.Each document collection can have a different performance level, allowing more throughput to be specified for frequently accessed collections, and less throughput for infrequently accessed collections.

Každá kolekce dokumentů se skládá z nuly nebo více dokumentů JSON.Each document collection consists of zero or more JSON documents. Dokumenty v kolekci jsou bez schématu, takže je nemusíte sdílet se stejnou strukturou nebo poli.Documents in a collection are schema-free, and so do not need to share the same structure or fields. Když se do kolekce dokumentů přidají dokumenty, Cosmos DB je automaticky indexovat a budou k dispozici pro dotazování.As documents are added to a document collection, Cosmos DB automatically indexes them and they become available to be queried.

Pro účely vývoje lze databázi dokumentů také spotřebovat prostřednictvím emulátoru.For development purposes, a document database can also be consumed through an emulator. Pomocí emulátoru se aplikace dají vyvíjet a testovat místně, aniž byste museli vytvářet předplatné Azure ani náklady.Using the emulator, applications can be developed and tested locally, without creating an Azure subscription or incurring any costs. Další informace o emulátoru naleznete v tématu vývoj místně pomocí emulátoru Azure Cosmos DB.For more information about the emulator, see Developing locally with the Azure Cosmos DB Emulator.

Tento článek a doprovodná ukázková aplikace znázorňuje aplikaci seznamu úkolů, kde jsou úkoly uložené v databázi dokumentů Azure Cosmos DB.This article, and accompanying sample application, demonstrates a Todo list application where the tasks are stored in an Azure Cosmos DB document database. Další informace o ukázkové aplikaci najdete v tématu Princip ukázky.For more information about the sample application, see Understanding the sample.

Další informace o Azure Cosmos DB najdete v dokumentaci k Azure Cosmos DB.For more information about Azure Cosmos DB, see the Azure Cosmos DB Documentation.

Poznámka

Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet před tím, než začnete.If you don't have an Azure subscription, create a free account before you begin.

NastaveníSetup

Postup pro integraci databáze dokumentů Azure Cosmos DB do :::no-loc(Xamarin.Forms)::: aplikace je následující:The process for integrating an Azure Cosmos DB document database into a :::no-loc(Xamarin.Forms)::: application is as follows:

  1. Vytvořte účet Cosmos DB.Create a Cosmos DB account. Další informace najdete v tématu Vytvoření účtu Azure Cosmos DB.For more information, see Create an Azure Cosmos DB account.
  2. Do projektů platforem v řešení přidejte balíček NuGet klientské knihovny Azure Cosmos DB .NET Standard :::no-loc(Xamarin.Forms)::: .Add the Azure Cosmos DB .NET Standard client library NuGet package to the platform projects in the :::no-loc(Xamarin.Forms)::: solution.
  3. Přidejte using direktivy pro Microsoft.Azure.Documents Microsoft.Azure.Documents.Client Microsoft.Azure.Documents.Linq obory názvů, a do tříd, které budou mít přístup k účtu Cosmos DB.Add using directives for the Microsoft.Azure.Documents, Microsoft.Azure.Documents.Client, and Microsoft.Azure.Documents.Linq namespaces to classes that will access the Cosmos DB account.

Po provedení tohoto postupu lze pomocí klientské knihovny Azure Cosmos DB .NET Standard nakonfigurovat a spustit požadavky na databázi dokumentů.After performing these steps, the Azure Cosmos DB .NET Standard client library can be used to configure and execute requests against the document database.

Poznámka

Klientská knihovna Azure Cosmos DB .NET Standard může být nainstalována pouze do projektů platforem a ne do přenositelného projektu knihovny tříd (PCL).The Azure Cosmos DB .NET Standard client library can only be installed into platform projects, and not into a Portable Class Library (PCL) project. Proto je ukázková aplikace projektem sdíleného přístupu (SAP), aby se předešlo duplicitám kódu.Therefore, the sample application is a Shared Access Project (SAP) to avoid code duplication. DependencyServiceTřída však může být použita v projektu PCL k vyvolání Azure Cosmos DB .NET Standard kód klientské knihovny obsažené v projektech specifických pro platformu.However, the DependencyService class can be used in a PCL project to invoke Azure Cosmos DB .NET Standard client library code contained in platform-specific projects.

Spotřebovává se Azure Cosmos DB účet.Consuming the Azure Cosmos DB account

DocumentClientTyp zapouzdřuje koncový bod, přihlašovací údaje a zásady připojení používané pro přístup k účtu Azure Cosmos DB a slouží ke konfiguraci a provádění požadavků na účet.The DocumentClient type encapsulates the endpoint, credentials, and connection policy used to access the Azure Cosmos DB account, and is used to configure and execute requests against the account. Následující příklad kódu ukazuje, jak vytvořit instanci této třídy:The following code example demonstrates how to create an instance of this class:

DocumentClient client = new DocumentClient(new Uri(Constants.EndpointUri), Constants.PrimaryKey);

K konstruktoru musí být poskytnutý Cosmos DB identifikátor URI a primární klíč DocumentClient .The Cosmos DB Uri and primary key must be provided to the DocumentClient constructor. Ty se dají získat na webu Azure Portal.These can be obtained from the Azure Portal. Další informace najdete v tématu připojení k účtu Azure Cosmos DB.For more information, see Connect to a Azure Cosmos DB account.

Vytvoření databázeCreating a Database

Databáze dokumentů je logický kontejner pro kolekce dokumentů a uživatele a je možné ho vytvořit na webu Azure Portal nebo programově pomocí DocumentClient.CreateDatabaseIfNotExistsAsync metody:A document database is a logical container for document collections and users, and can be created in the Azure Portal, or programmatically using the DocumentClient.CreateDatabaseIfNotExistsAsync method:

public async Task CreateDatabase(string databaseName)
{
  ...
  await client.CreateDatabaseIfNotExistsAsync(new Database
  {
    Id = databaseName
  });
  ...
}

CreateDatabaseIfNotExistsAsyncMetoda Určuje Database objekt jako argument s objektem, který určuje Database název databáze jako Id vlastnost.The CreateDatabaseIfNotExistsAsync method specifies a Database object as an argument, with the Database object specifying the database name as its Id property. CreateDatabaseIfNotExistsAsyncMetoda vytvoří databázi, pokud neexistuje, nebo vrátí databázi, pokud již existuje.The CreateDatabaseIfNotExistsAsync method creates the database if it doesn't exist, or returns the database if it already exists. Ukázková aplikace však ignoruje všechna data vrácená CreateDatabaseIfNotExistsAsync metodou.However, the sample application ignores any data returned by the CreateDatabaseIfNotExistsAsync method.

Poznámka

CreateDatabaseIfNotExistsAsyncMetoda vrátí Task<ResourceResponse<Database>> objekt a stavový kód odpovědi lze zkontrolovat a zjistit, zda byla databáze vytvořena nebo byla vrácena existující databáze.The CreateDatabaseIfNotExistsAsync method returns a Task<ResourceResponse<Database>> object, and the status code of the response can be checked to determine whether a database was created, or an existing database was returned.

Vytvoření kolekce dokumentůCreating a Document Collection

Kolekce dokumentů je kontejner pro dokumenty JSON a je možné ho vytvořit na webu Azure Portal nebo programově pomocí DocumentClient.CreateDocumentCollectionIfNotExistsAsync metody:A document collection is a container for JSON documents, and can be created in the Azure Portal, or programmatically using the DocumentClient.CreateDocumentCollectionIfNotExistsAsync method:

public async Task CreateDocumentCollection(string databaseName, string collectionName)
{
  ...
  // Create collection with 400 RU/s
  await client.CreateDocumentCollectionIfNotExistsAsync(
    UriFactory.CreateDatabaseUri(databaseName),
    new DocumentCollection
    {
      Id = collectionName
    },
    new RequestOptions
    {
      OfferThroughput = 400
    });
  ...
}

CreateDocumentCollectionIfNotExistsAsyncMetoda vyžaduje dva povinné argumenty – název databáze zadaný jako a Uri a DocumentCollection objekt.The CreateDocumentCollectionIfNotExistsAsync method requires two compulsory arguments – a database name specified as a Uri, and a DocumentCollection object. DocumentCollectionObjekt představuje kolekci dokumentů, jejíž název je zadán s Id vlastností.The DocumentCollection object represents a document collection whose name is specified with the Id property. CreateDocumentCollectionIfNotExistsAsyncMetoda vytvoří kolekci dokumentů, pokud neexistuje, nebo kolekci dokumentů vrátí, pokud již existuje.The CreateDocumentCollectionIfNotExistsAsync method creates the document collection if it doesn't exist, or returns the document collection if it already exists. Ukázková aplikace však ignoruje všechna data vrácená CreateDocumentCollectionIfNotExistsAsync metodou.However, the sample application ignores any data returned by the CreateDocumentCollectionIfNotExistsAsync method.

Poznámka

CreateDocumentCollectionIfNotExistsAsyncMetoda vrátí Task<ResourceResponse<DocumentCollection>> objekt a stavový kód odpovědi lze zkontrolovat a zjistit, zda byla kolekce dokumentů vytvořena nebo byla vrácena existující kolekce dokumentů.The CreateDocumentCollectionIfNotExistsAsync method returns a Task<ResourceResponse<DocumentCollection>> object, and the status code of the response can be checked to determine whether a document collection was created, or an existing document collection was returned.

Volitelně CreateDocumentCollectionIfNotExistsAsync může metoda také určit RequestOptions objekt, který zapouzdřuje možnosti, které lze zadat pro žádosti vydané Cosmos DBmu účtu.Optionally, the CreateDocumentCollectionIfNotExistsAsync method can also specify a RequestOptions object, which encapsulates options that can be specified for requests issued to the Cosmos DB account. Tato RequestOptions.OfferThroughput vlastnost slouží k definování úrovně výkonu kolekce dokumentů a v ukázkové aplikaci je nastavena na 400 jednotek žádostí za sekundu.The RequestOptions.OfferThroughput property is used to define the performance level of the document collection, and in the sample application, is set to 400 request units per second. Tato hodnota by se měla zvýšit nebo snížit v závislosti na tom, jestli bude kolekce často nebo zřídka dostupná.This value should be increased or decreased depending on whether the collection will be frequently or infrequently accessed.

Důležité

Všimněte si, že CreateDocumentCollectionIfNotExistsAsync Metoda vytvoří novou kolekci s vyhrazenou propustností, která bude mít dopad na ceny.Note that the CreateDocumentCollectionIfNotExistsAsync method will create a new collection with a reserved throughput, which has pricing implications.

Načítání dokumentů kolekce dokumentůRetrieving Document Collection Documents

Obsah kolekce dokumentů lze načíst vytvořením a spuštěním dotazu dokumentu.The contents of a document collection can be retrieved by creating and executing a document query. Vytvoří se dotaz na dokument s DocumentClient.CreateDocumentQuery metodou:A document query is created with the DocumentClient.CreateDocumentQuery method:

public async Task<List<TodoItem>> GetTodoItemsAsync()
{
  ...
  var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
            .AsDocumentQuery();
  while (query.HasMoreResults)
  {
    Items.AddRange(await query.ExecuteNextAsync<TodoItem>());
  }
  ...
}

Tento dotaz asynchronně načte všechny dokumenty ze zadané kolekce a umístí dokumenty do List<TodoItem> kolekce k zobrazení.This query asynchronously retrieves all the documents from the specified collection, and places the documents in a List<TodoItem> collection for display.

CreateDocumentQuery<T>Metoda Určuje Uri argument reprezentující kolekci, na kterou by se měly dotazovat dokumenty.The CreateDocumentQuery<T> method specifies a Uri argument that represents the collection that should be queried for documents. V tomto příkladu collectionLink je proměnná pole na úrovni třídy, které určuje Uri , který představuje kolekci dokumentů pro načtení dokumentů:In this example, the collectionLink variable is a class-level field that specifies the Uri that represents the document collection to retrieve documents from:

Uri collectionLink = UriFactory.CreateDocumentCollectionUri(Constants.DatabaseName, Constants.CollectionName);

CreateDocumentQuery<T>Metoda vytvoří dotaz, který je spuštěn synchronně, a vrátí IQueryable<T> objekt.The CreateDocumentQuery<T> method creates a query that is executed synchronously, and returns an IQueryable<T> object. AsDocumentQueryMetoda však převede IQueryable<T> objekt na IDocumentQuery<T> objekt, který lze spustit asynchronně.However, the AsDocumentQuery method converts the IQueryable<T> object to an IDocumentQuery<T> object which can be executed asynchronously. Asynchronní dotaz je proveden s IDocumentQuery<T>.ExecuteNextAsync metodou, která načte další stránku výsledků z databáze dokumentu s vlastností, která IDocumentQuery<T>.HasMoreResults Určuje, zda jsou z dotazu vráceny další výsledky.The asynchronous query is executed with the IDocumentQuery<T>.ExecuteNextAsync method, which retrieves the next page of results from the document database, with the IDocumentQuery<T>.HasMoreResults property indicating whether there are additional results to be returned from the query.

Dokumenty lze filtrovat na straně serveru zahrnutím Where klauzule do dotazu, který pro dotaz na kolekci dokumentů používá predikát filtrování:Documents can be filtered server side by including a Where clause in the query, which applies a filtering predicate to the query against the document collection:

var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
          .Where(f => f.Done != true)
          .AsDocumentQuery();

Tento dotaz načte všechny dokumenty z kolekce, jejichž Done vlastnost je rovna false .This query retrieves all documents from the collection whose Done property is equal to false.

Vložení dokumentu do kolekce dokumentůInserting a Document into a Document Collection

Dokumenty jsou uživatelem definovaný obsah JSON a lze jej vložit do kolekce dokumentů pomocí DocumentClient.CreateDocumentAsync metody:Documents are user defined JSON content, and can be inserted into a document collection with the DocumentClient.CreateDocumentAsync method:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.CreateDocumentAsync(collectionLink, item);
  ...
}

CreateDocumentAsyncMetoda Určuje Uri argument reprezentující kolekci, do které má být vložen dokument, a object argument reprezentující dokument, který má být vložen.The CreateDocumentAsync method specifies a Uri argument that represents the collection the document should be inserted into, and an object argument that represents the document to be inserted.

Nahrazení dokumentu v kolekci dokumentůReplacing a Document in a Document Collection

Dokumenty lze v kolekci dokumentů nahradit DocumentClient.ReplaceDocumentAsync metodou:Documents can be replaced in a document collection with the DocumentClient.ReplaceDocumentAsync method:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, item.Id), item);
  ...
}

ReplaceDocumentAsyncMetoda Určuje Uri argument reprezentující dokument v kolekci, který by měl být nahrazen, a object argument, který představuje aktualizovaná data dokumentu.The ReplaceDocumentAsync method specifies a Uri argument that represents the document in the collection that should be replaced, and an object argument that represents the updated document data.

Odstranění dokumentu z kolekce dokumentůDeleting a Document from a Document Collection

Dokument lze odstranit z kolekce dokumentů pomocí DocumentClient.DeleteDocumentAsync metody:A document can be deleted from a document collection with the DocumentClient.DeleteDocumentAsync method:

public async Task DeleteTodoItemAsync(string id)
{
  ...
  await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, id));
  ...
}

DeleteDocumentAsyncMetoda Určuje Uri argument reprezentující dokument v kolekci, který má být odstraněn.The DeleteDocumentAsync method specifies a Uri argument that represents the document in the collection that should be deleted.

Odstranění kolekce dokumentůDeleting a Document Collection

Kolekci dokumentů lze odstranit z databáze pomocí DocumentClient.DeleteDocumentCollectionAsync metody:A document collection can be deleted from a database with the DocumentClient.DeleteDocumentCollectionAsync method:

await client.DeleteDocumentCollectionAsync(collectionLink);

DeleteDocumentCollectionAsyncMetoda Určuje Uri argument reprezentující kolekci dokumentů, která má být odstraněna.The DeleteDocumentCollectionAsync method specifies a Uri argument that represents the document collection to be deleted. Všimněte si, že při vyvolání této metody budou odstraněny také dokumenty uložené v kolekci.Note that invoking this method will also delete the documents stored in the collection.

Odstranění databázeDeleting a Database

Databázi je možné odstranit z Cosmos DB databázového účtu pomocí DocumentClient.DeleteDatabaesAsync metody:A database can be deleted from a Cosmos DB database account with the DocumentClient.DeleteDatabaesAsync method:

await client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri(Constants.DatabaseName));

DeleteDatabaseAsyncMetoda Určuje Uri argument reprezentující databázi, která má být odstraněna.The DeleteDatabaseAsync method specifies a Uri argument that represents the database to be deleted. Všimněte si, že při vyvolání této metody dojde také k odstranění kolekcí dokumentů uložených v databázi a dokumentů uložených v kolekcích dokumentů.Note that invoking this method will also delete the document collections stored in the database, and the documents stored in the document collections.

ShrnutíSummary

Tento článek vysvětluje, jak pomocí Azure Cosmos DB .NET Standard klientské knihovny integrovat Azure Cosmos DB databázi dokumentů do :::no-loc(Xamarin.Forms)::: aplikace.This article explained how to use the Azure Cosmos DB .NET Standard client library to integrate an Azure Cosmos DB document database into a :::no-loc(Xamarin.Forms)::: application. Azure Cosmos DB databáze dokumentů je databáze NoSQL, která poskytuje přístup s nízkou latencí k dokumentům JSON, nabízí rychlou, vysoce dostupnou a škálovatelnou databázovou službu pro aplikace, které vyžadují bezproblémové škálování a globální replikaci.An Azure Cosmos DB document database is a NoSQL database that provides low latency access to JSON documents, offering a fast, highly available, scalable database service for applications that require seamless scale and global replication.