Udostępnij za pośrednictwem

Korzystanie z bazy danych dokumentów usługi Azure Cosmos DB w usłudze Xamarin.Forms

  • Artykuł

Baza danych dokumentów usługi Azure Cosmos DB to baza danych NoSQL, która zapewnia dostęp o małych opóźnieniach do dokumentów JSON, oferując szybką, skalowalną usługę bazy danych o wysokiej dostępności dla aplikacji wymagających bezproblemowej replikacji globalnej i skalowania globalnego. W tym artykule wyjaśniono, jak zintegrować bazę danych dokumentów usługi Azure Cosmos DB z aplikacją Xamarin.Forms przy użyciu biblioteki klienta .NET Standard usługi Azure Cosmos DB.

Wideo dotyczące usługi Microsoft Azure Cosmos DB

Konto bazy danych dokumentów usługi Azure Cosmos DB można aprowizować przy użyciu subskrypcji platformy Azure. Każde konto bazy danych może mieć zero lub więcej baz danych. Baza danych dokumentów w usłudze Azure Cosmos DB jest kontenerem logicznym dla kolekcji dokumentów i użytkowników.

Baza danych dokumentów usługi Azure Cosmos DB może zawierać co najmniej zero kolekcji dokumentów. Każda kolekcja dokumentów może mieć inny poziom wydajności, co umożliwia określenie większej przepływności dla często używanych kolekcji oraz mniejszej przepływności dla rzadko używanych kolekcji.

Każda kolekcja dokumentów składa się z co najmniej zera dokumentów JSON. Dokumenty w kolekcji są wolne od schematu, dlatego nie muszą współużytkować tej samej struktury ani pól. W miarę dodawania dokumentów do kolekcji dokumentów usługa Azure Cosmos DB automatycznie je indeksuje i staje się dostępna do odpytowania.

W celach programistycznych można również używać bazy danych dokumentów za pośrednictwem emulatora. Za pomocą emulatora aplikacje można opracowywać i testować lokalnie bez tworzenia subskrypcji platformy Azure ani ponoszenia kosztów. Aby uzyskać więcej informacji na temat emulatora, zobacz Programowanie lokalnie za pomocą emulatora usługi Azure Cosmos DB.

W tym artykule i towarzyszącej przykładowej aplikacji przedstawiono aplikację listy zadań do wykonania, w której zadania są przechowywane w bazie danych dokumentów usługi Azure Cosmos DB. Aby uzyskać więcej informacji na temat przykładowej aplikacji, zobacz Opis przykładu.

Aby uzyskać więcej informacji na temat usługi Azure Cosmos DB, zobacz dokumentację usługi Azure Cosmos DB.

Uwaga

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Ustawienia

Proces integrowania bazy danych dokumentów usługi Azure Cosmos DB z aplikacją Xamarin.Forms jest następujący:

  1. Utwórz konto usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Tworzenie konta usługi Azure Cosmos DB.
  2. Dodaj pakiet NuGet biblioteki klienta .NET Standard usługi Azure Cosmos DB do projektów platformy w rozwiązaniuXamarin.Forms.
  3. Dodaj using dyrektywy dla Microsoft.Azure.Documentsprzestrzeni nazw , Microsoft.Azure.Documents.Clienti Microsoft.Azure.Documents.Linq do klas, które będą uzyskiwać dostęp do konta usługi Azure Cosmos DB.

Po wykonaniu tych kroków można użyć biblioteki klienta .NET Standard usługi Azure Cosmos DB do konfigurowania i wykonywania żądań względem bazy danych dokumentów.

Uwaga

Bibliotekę klienta .NET Standard usługi Azure Cosmos DB można zainstalować tylko w projektach platformy, a nie w projekcie Portable Class Library (PCL). W związku z tym przykładowa aplikacja jest projektem dostępu współdzielonego (SAP), aby uniknąć duplikowania kodu. DependencyService Jednak klasa może być używana w projekcie PCL do wywoływania kodu biblioteki klienta .NET Standard usługi Azure Cosmos DB zawartego w projektach specyficznych dla platformy.

Korzystanie z konta usługi Azure Cosmos DB

Typ DocumentClient hermetyzuje punkt końcowy, poświadczenia i zasady połączenia używane do uzyskiwania dostępu do konta usługi Azure Cosmos DB i służą do konfigurowania i wykonywania żądań względem konta. W poniższym przykładzie kodu pokazano, jak utworzyć wystąpienie tej klasy:

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

Identyfikator URI i klucz podstawowy usługi Azure Cosmos DB muszą zostać dostarczone do konstruktora DocumentClient . Można je uzyskać w witrynie Azure Portal. Aby uzyskać więcej informacji, zobacz Połączenie do konta usługi Azure Cosmos DB.

Tworzenie bazy danych

Baza danych dokumentów to logiczny kontener kolekcji dokumentów i użytkowników, który można utworzyć w witrynie Azure Portal lub programowo przy użyciu DocumentClient.CreateDatabaseIfNotExistsAsync metody :

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

Metoda CreateDatabaseIfNotExistsAsync określa Database obiekt jako argument z obiektem Database określającym nazwę bazy danych jako jego Id właściwość. Metoda CreateDatabaseIfNotExistsAsync tworzy bazę danych, jeśli nie istnieje lub zwraca bazę danych, jeśli już istnieje. Jednak przykładowa aplikacja ignoruje wszystkie dane zwrócone przez metodę CreateDatabaseIfNotExistsAsync .

Uwaga

Metoda CreateDatabaseIfNotExistsAsync zwraca Task<ResourceResponse<Database>> obiekt, a kod stanu odpowiedzi można sprawdzić, aby określić, czy baza danych została utworzona, czy została zwrócona istniejąca baza danych.

Tworzenie kolekcji dokumentów

Kolekcja dokumentów jest kontenerem dokumentów JSON i można ją utworzyć w witrynie Azure Portal lub programowo przy użyciu 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 wymaga dwóch obowiązkowych argumentów — nazwy bazy danych określonej jako Uri, i DocumentCollection obiektu. Obiekt DocumentCollection reprezentuje kolekcję dokumentów, której nazwa jest określona z właściwością Id . Metoda CreateDocumentCollectionIfNotExistsAsync tworzy kolekcję dokumentów, jeśli nie istnieje lub zwraca kolekcję dokumentów, jeśli już istnieje. Jednak przykładowa aplikacja ignoruje wszystkie dane zwrócone przez metodę CreateDocumentCollectionIfNotExistsAsync .

Uwaga

Metoda CreateDocumentCollectionIfNotExistsAsync zwraca Task<ResourceResponse<DocumentCollection>> obiekt, a kod stanu odpowiedzi można sprawdzić, aby określić, czy kolekcja dokumentów została utworzona, czy też została zwrócona istniejąca kolekcja dokumentów.

CreateDocumentCollectionIfNotExistsAsync Opcjonalnie metoda może również określić RequestOptions obiekt, który hermetyzuje opcje, które można określić dla żądań wystawionych na koncie usługi Azure Cosmos DB. Właściwość RequestOptions.OfferThroughput służy do definiowania poziomu wydajności kolekcji dokumentów, a w przykładowej aplikacji jest ustawiona na 400 jednostek żądania na sekundę. Ta wartość powinna zostać zwiększona lub zmniejszona w zależności od tego, czy kolekcja będzie często lub rzadko uzyskiwana.

Ważne

Należy pamiętać, że CreateDocumentCollectionIfNotExistsAsync metoda utworzy nową kolekcję z zarezerwowaną przepływnością, która ma wpływ na ceny.

Pobieranie dokumentów kolekcji dokumentów

Zawartość kolekcji dokumentów można pobrać, tworząc i wykonując zapytanie o dokument. Zapytanie o dokument jest tworzone przy użyciu DocumentClient.CreateDocumentQuery metody :

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

To zapytanie asynchronicznie pobiera wszystkie dokumenty z określonej kolekcji i umieszcza dokumenty w List<TodoItem> kolekcji na potrzeby wyświetlania.

Metoda CreateDocumentQuery<T> określa Uri argument reprezentujący kolekcję, która ma być odpytywana dla dokumentów. W tym przykładzie zmienna collectionLink jest polem na poziomie klasy, które określa Uri , który reprezentuje kolekcję dokumentów w celu pobrania dokumentów z:

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

Metoda CreateDocumentQuery<T> tworzy zapytanie wykonywane synchronicznie i zwraca IQueryable<T> obiekt. AsDocumentQuery Jednak metoda konwertuje IQueryable<T> obiekt na IDocumentQuery<T> obiekt, który można wykonać asynchronicznie. Zapytanie asynchroniczne jest wykonywane za pomocą IDocumentQuery<T>.ExecuteNextAsync metody , która pobiera następną stronę wyników z bazy danych dokumentów z właściwością IDocumentQuery<T>.HasMoreResults wskazującą, czy z zapytania mają zostać zwrócone dodatkowe wyniki.

Dokumenty można filtrować po stronie serwera, dołączając klauzulę Where w zapytaniu, która stosuje predykat filtrowania do zapytania względem kolekcji dokumentów:

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

To zapytanie pobiera wszystkie dokumenty z kolekcji, której Done właściwość jest równa false.

Wstawianie dokumentu do kolekcji dokumentów

Dokumenty są zawartością JSON zdefiniowaną przez użytkownika i można je wstawić do kolekcji dokumentów przy użyciu DocumentClient.CreateDocumentAsync metody :

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

Metoda CreateDocumentAsync określa Uri argument reprezentujący kolekcję, do którego należy wstawić dokument, oraz object argument reprezentujący dokument do wstawienia.

Zastępowanie dokumentu w kolekcji dokumentów

Dokumenty można zastąpić w kolekcji DocumentClient.ReplaceDocumentAsync dokumentów metodą :

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

Metoda ReplaceDocumentAsync określa Uri argument reprezentujący dokument w kolekcji, który ma zostać zastąpiony, oraz object argument reprezentujący zaktualizowane dane dokumentu.

Usuwanie dokumentu z kolekcji dokumentów

Dokument można usunąć z kolekcji dokumentów przy użyciu DocumentClient.DeleteDocumentAsync metody :

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

Metoda DeleteDocumentAsync określa Uri argument reprezentujący dokument w kolekcji, który ma zostać usunięty.

Usuwanie kolekcji dokumentów

Kolekcję dokumentów można usunąć z bazy danych przy użyciu DocumentClient.DeleteDocumentCollectionAsync metody :

await client.DeleteDocumentCollectionAsync(collectionLink);

Metoda DeleteDocumentCollectionAsync określa Uri argument reprezentujący kolekcję dokumentów do usunięcia. Należy pamiętać, że wywołanie tej metody spowoduje również usunięcie dokumentów przechowywanych w kolekcji.

Usuwanie bazy danych

Bazę danych można usunąć z konta bazy danych usługi Azure Cosmos DB przy użyciu DocumentClient.DeleteDatabaesAsync metody :

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

Metoda DeleteDatabaseAsync określa Uri argument reprezentujący bazę danych do usunięcia. Należy pamiętać, że wywołanie tej metody spowoduje również usunięcie kolekcji dokumentów przechowywanych w bazie danych oraz dokumentów przechowywanych w kolekcjach dokumentów.

Podsumowanie

W tym artykule wyjaśniono, jak używać biblioteki klienta .NET Standard usługi Azure Cosmos DB do integracji bazy danych dokumentów usługi Azure Cosmos DB z aplikacją Xamarin.Forms . Baza danych dokumentów usługi Azure Cosmos DB to baza danych NoSQL, która zapewnia dostęp o małych opóźnieniach do dokumentów JSON, oferując szybką, skalowalną usługę bazy danych o wysokiej dostępności dla aplikacji wymagających bezproblemowej replikacji globalnej i skalowania globalnego.