Sdílet prostřednictvím

Využívání databáze dokumentů Azure Cosmos DB v Xamarin.Forms

  • Článek

Databáze dokumentů Azure Cosmos DB je databáze NoSQL, která poskytuje přístup k dokumentům JSON s nízkou latencí a 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. Tento článek vysvětluje, jak pomocí klientské knihovny Azure Cosmos DB .NET Standard integrovat databázi dokumentů Azure Cosmos DB do Xamarin.Forms aplikace.

Video o službě Microsoft Azure Cosmos DB

Účet databáze dokumentů Azure Cosmos DB je možné zřídit pomocí předplatného Azure. Každý databázový účet může mít nula nebo více databází. Databáze dokumentů ve službě Azure Cosmos DB je logický kontejner pro kolekce dokumentů a uživatele.

Databáze dokumentů Azure Cosmos DB může obsahovat nula nebo více kolekcí dokumentů. 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.

Každá kolekce dokumentů se skládá z nuly nebo více dokumentů JSON. Dokumenty v kolekci jsou bez schématu a proto nemusí sdílet stejnou strukturu nebo pole. Při přidání dokumentů do kolekce dokumentů je Azure Cosmos DB automaticky indexuje a zpřístupní se k dotazování.

Pro účely vývoje je možné databázi dokumentů využívat také prostřednictvím emulátoru. Pomocí emulátoru je možné vyvíjet a testovat aplikace místně bez vytvoření předplatného Azure nebo bez jakýchkoli nákladů. Další informace o emulátoru najdete v tématu Místní vývoj pomocí emulátoru služby Azure Cosmos DB.

Tento článek a doprovodná ukázková aplikace ukazuje aplikaci seznamu úkolů, ve které jsou úlohy uložené v databázi dokumentů Azure Cosmos DB. Další informace o ukázkové aplikaci najdete v tématu Vysvětlení ukázky.

Další informace o službě Azure Cosmos DB najdete v dokumentaci ke službě Azure Cosmos DB.

Poznámka:

Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet před tím, než začnete.

Nastavení

Proces integrace databáze dokumentů Azure Cosmos DB do Xamarin.Forms aplikace je následující:

  1. Vytvořit účet služby Azure Cosmos DB. Další informace najdete v tématu Vytvoření účtu služby Azure Cosmos DB.
  2. Přidejte balíček NuGet klientské knihovny .NET Standard služby Azure Cosmos DB do projektů platformy v Xamarin.Forms řešení.
  3. Přidejte using direktivy pro Microsoft.Azure.Documentstřídy , Microsoft.Azure.Documents.Clienta Microsoft.Azure.Documents.Linq obory názvů, které budou přistupovat k účtu služby Azure Cosmos DB.

Po provedení těchto kroků je možné klientskou knihovnu Azure Cosmos DB .NET Standard použít ke konfiguraci a provádění požadavků na databázi dokumentů.

Poznámka:

Klientskou knihovnu Azure Cosmos DB .NET Standard je možné nainstalovat pouze do projektů platformy, a ne do projektu PCL (Portable Class Library). Proto je ukázková aplikace projektem sdíleného přístupu (SAP), aby nedocházelo k duplikaci kódu. Třídu DependencyService však lze použít v projektu PCL k vyvolání kódu klientské knihovny .NET Standard služby Azure Cosmos DB obsaženého v projektech specifických pro platformu.

Využívání účtu služby Azure Cosmos DB

Typ DocumentClient zapouzdřuje koncový bod, přihlašovací údaje a zásady připojení používané pro přístup k účtu služby Azure Cosmos DB a slouží ke konfiguraci a spouštění požadavků na tento účet. Následující příklad kódu ukazuje, jak vytvořit instanci této třídy:

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

Identifikátor URI a primární klíč služby Azure Cosmos DB musí být poskytnuty konstruktoru DocumentClient . Ty je možné získat z webu Azure Portal. Další informace najdete v tématu Připojení k účtu služby Azure Cosmos DB.

Vytvoření databáze

Databáze dokumentů je logický kontejner pro kolekce dokumentů a uživatele a lze ji vytvořit na webu Azure Portal nebo programově pomocí DocumentClient.CreateDatabaseIfNotExistsAsync této metody:

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

Metoda CreateDatabaseIfNotExistsAsync určuje Database objekt jako argument s objektem Database určujícím název databáze jako jeho Id vlastnost. Metoda CreateDatabaseIfNotExistsAsync vytvoří databázi, pokud neexistuje, nebo vrátí databázi, pokud již existuje. Ukázková aplikace však ignoruje všechna data vrácená metodou CreateDatabaseIfNotExistsAsync .

Poznámka:

Metoda CreateDatabaseIfNotExistsAsync vrátí Task<ResourceResponse<Database>> objekt a stavový kód odpovědi lze zkontrolovat, zda byla vytvořena databáze nebo zda byla vrácena existující databáze.

Vytvoření kolekce dokumentů

Kolekce dokumentů je kontejner pro dokumenty JSON a dá se vytvořit na webu Azure Portal nebo programově pomocí DocumentClient.CreateDocumentCollectionIfNotExistsAsync metody:

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

Metoda CreateDocumentCollectionIfNotExistsAsync vyžaduje dva povinné argumenty – název databáze zadaný jako Uria DocumentCollection objekt. Objekt DocumentCollection představuje kolekci dokumentů, jejíž název je určen vlastností Id . Metoda CreateDocumentCollectionIfNotExistsAsync vytvoří kolekci dokumentů, pokud neexistuje, nebo vrátí kolekci dokumentů, pokud již existuje. Ukázková aplikace však ignoruje všechna data vrácená metodou CreateDocumentCollectionIfNotExistsAsync .

Poznámka:

Metoda CreateDocumentCollectionIfNotExistsAsync vrátí Task<ResourceResponse<DocumentCollection>> objekt a stavový kód odpovědi lze zkontrolovat, zda byla vytvořena kolekce dokumentů nebo zda byla vrácena existující kolekce dokumentů.

CreateDocumentCollectionIfNotExistsAsync Volitelně může metoda také zadat RequestOptions objekt, který zapouzdřuje možnosti, které lze zadat pro požadavky vydané pro účet služby Azure Cosmos DB. Vlastnost RequestOptions.OfferThroughput se používá k definování úrovně výkonu kolekce dokumentů a v ukázkové aplikaci je nastavena na 400 jednotek žádostí za sekundu. Tato hodnota by se měla zvýšit nebo snížit v závislosti na tom, jestli bude kolekce často nebo zřídka přístupná.

Důležité

Všimněte si, že CreateDocumentCollectionIfNotExistsAsync metoda vytvoří novou kolekci s rezervovanou propustností, která má vliv na ceny.

Načítání dokumentů kolekce dokumentů

Obsah kolekce dokumentů lze načíst vytvořením a spuštěním dotazu na dokument. Pomocí metody se vytvoří dotaz na DocumentClient.CreateDocumentQuery dokument:

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 pro zobrazení.

Metoda CreateDocumentQuery<T> určuje Uri argument, který představuje kolekci, která by se měla dotazovat na dokumenty. V tomto příkladu collectionLink je proměnná pole na úrovni třídy, které určuje Uri kolekci dokumentů pro načtení dokumentů z:

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

Metoda CreateDocumentQuery<T> vytvoří dotaz, který se spouští synchronně, a vrátí IQueryable<T> objekt. Metoda však převede IQueryable<T> objekt na IDocumentQuery<T> objekt, AsDocumentQuery který lze spustit asynchronně. Asynchronní dotaz se provede metodou IDocumentQuery<T>.ExecuteNextAsync , která načte další stránku výsledků z databáze dokumentů s IDocumentQuery<T>.HasMoreResults vlastností označující, zda se z dotazu mají vrátit další výsledky.

Dokumenty lze filtrovat na straně serveru zahrnutím Where klauzule do dotazu, která aplikuje predikát filtrování na dotaz proti kolekci dokumentů:

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.

Vložení dokumentu do kolekce dokumentů

Dokumenty jsou uživatelem definovaný obsah JSON a lze je vložit do kolekce dokumentů pomocí DocumentClient.CreateDocumentAsync metody:

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

Metoda CreateDocumentAsync určuje Uri argument, který představuje kolekci, do které má být dokument vložen, a object argument, který představuje dokument, který má být vložen.

Nahrazení dokumentu v kolekci dokumentů

Dokumenty lze v kolekci dokumentů nahradit metodou DocumentClient.ReplaceDocumentAsync :

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

Metoda ReplaceDocumentAsync určuje Uri argument, který představuje dokument v kolekci, které by měly být nahrazeny, a object argument, který představuje aktualizovaná data dokumentu.

Odstranění dokumentu z kolekce dokumentů

Dokument lze odstranit z kolekce dokumentů pomocí DocumentClient.DeleteDocumentAsync metody:

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

Metoda DeleteDocumentAsync určuje Uri argument, který představuje dokument v kolekci, která by měla být odstraněna.

Odstranění kolekce dokumentů

Kolekci dokumentů lze odstranit z databáze pomocí DocumentClient.DeleteDocumentCollectionAsync metody:

await client.DeleteDocumentCollectionAsync(collectionLink);

Metoda DeleteDocumentCollectionAsync určuje Uri argument, který představuje kolekci dokumentů, která se má odstranit. Všimněte si, že vyvolání této metody odstraní také dokumenty uložené v kolekci.

Odstranění databáze

Databázi je možné odstranit z účtu databáze Azure Cosmos DB pomocí DocumentClient.DeleteDatabaesAsync této metody:

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

Metoda DeleteDatabaseAsync určuje Uri argument, který představuje databázi, která má být odstraněna. Všimněte si, že vyvolání této metody odstraní také kolekce dokumentů uložené v databázi a dokumenty uložené v kolekcích dokumentů.

Shrnutí

Tento článek vysvětluje, jak pomocí klientské knihovny Azure Cosmos DB .NET Standard integrovat databázi dokumentů Azure Cosmos DB do Xamarin.Forms aplikace. Databáze dokumentů Azure Cosmos DB je databáze NoSQL, která poskytuje přístup k dokumentům JSON s nízkou latencí a 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.