Consumir um Banco de Dados de Documentos do Azure Cosmos DB em Xamarin.Forms

  • Artigo

Um banco de dados de documentos do Azure Cosmos DB é um banco de dados NoSQL que fornece acesso de baixa latência a documentos JSON, oferecendo um serviço de banco de dados rápido, altamente disponível e escalável para aplicativos que exigem escala perfeita e replicação global. Este artigo explica como usar a biblioteca de cliente do Azure Cosmos DB .NET Standard para integrar um banco de dados de documentos do Azure Cosmos DB em um Xamarin.Forms aplicativo.

Vídeo do Microsoft Azure Cosmos DB

Uma conta de banco de dados de documentos do Azure Cosmos DB pode ser provisionada usando uma assinatura do Azure. Cada conta de banco de dados pode ter zero ou mais bancos de dados. Um banco de dados de documentos no Azure Cosmos DB é um contêiner lógico para coleções de documentos e usuários.

Um banco de dados de documentos do Azure Cosmos DB pode conter zero ou mais coleções de documentos. Cada coleção de documentos pode ter um nível de desempenho diferente, permitindo que mais taxa de transferência seja especificada para coleções acessadas com frequência e menos taxa de transferência para coleções acessadas com pouca frequência.

Cada coleção de documentos consiste em zero ou mais documentos JSON. Os documentos em uma coleção são livres de esquema e, portanto, não precisam compartilhar a mesma estrutura ou campos. À medida que os documentos são adicionados a uma coleção de documentos, o Azure Cosmos DB os indexa automaticamente e eles ficam disponíveis para consulta.

Para fins de desenvolvimento, um banco de dados de documentos também pode ser consumido por meio de um emulador. Usando o emulador, os aplicativos podem ser desenvolvidos e testados localmente, sem criar uma assinatura do Azure ou incorrer em quaisquer custos. Para obter mais informações sobre o emulador, consulte Desenvolvendo localmente com o emulador do Azure Cosmos DB.

Este artigo e o aplicativo de exemplo que o acompanha demonstram um aplicativo de lista Todo onde as tarefas são armazenadas em um banco de dados de documentos do Azure Cosmos DB. Para obter mais informações sobre o aplicativo de exemplo, consulte Noções básicas sobre o exemplo.

Para obter mais informações sobre o Azure Cosmos DB, consulte a Documentação do Azure Cosmos DB.

Observação

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Instalação

O processo para integrar um banco de dados de documentos do Azure Cosmos DB em um Xamarin.Forms aplicativo é o seguinte:

  1. Criar uma conta do Azure Cosmos DB. Para obter mais informações, consulte Criar uma conta do Azure Cosmos DB.
  2. Adicione o pacote NuGet da biblioteca de cliente do Azure Cosmos DB .NET Standard aos projetos de plataforma na Xamarin.Forms solução.
  3. Adicione using diretivas para o Microsoft.Azure.Documents, Microsoft.Azure.Documents.Cliente Microsoft.Azure.Documents.Linq namespaces às classes que acessarão a conta do Azure Cosmos DB.

Depois de executar essas etapas, a biblioteca de cliente do Azure Cosmos DB .NET Standard pode ser usada para configurar e executar solicitações no banco de dados de documentos.

Observação

A biblioteca de cliente do Azure Cosmos DB .NET Standard só pode ser instalada em projetos de plataforma e não em um projeto de Biblioteca de Classes Portátil (PCL). Portanto, o aplicativo de exemplo é um projeto de acesso compartilhado (SAP) para evitar a duplicação de código. No entanto, a DependencyService classe pode ser usada em um projeto PCL para invocar o código da biblioteca de cliente do Azure Cosmos DB .NET Standard contido em projetos específicos da plataforma.

Consumindo a conta do Azure Cosmos DB

O DocumentClient tipo encapsula o ponto de extremidade, as credenciais e a política de conexão usados para acessar a conta do Azure Cosmos DB e é usado para configurar e executar solicitações na conta. O exemplo de código a seguir demonstra como criar uma instância dessa classe:

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

O Uri do Azure Cosmos DB e a chave primária devem ser fornecidos ao DocumentClient construtor. Eles podem ser obtidos no Portal do Azure. Para obter mais informações, consulte Conectar-se a uma conta do Azure Cosmos DB.

Criar um banco de dados

Um banco de dados de documentos é um contêiner lógico para coleções de documentos e usuários e pode ser criado no Portal do Azure ou programaticamente usando o DocumentClient.CreateDatabaseIfNotExistsAsync método:

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

O CreateDatabaseIfNotExistsAsync método especifica um Database objeto como um argumento, com o Database objeto especificando o nome do banco de dados como sua Id propriedade. O CreateDatabaseIfNotExistsAsync método cria o banco de dados se ele não existir ou retorna o banco de dados se ele já existir. No entanto, o aplicativo de exemplo ignora todos os dados retornados pelo CreateDatabaseIfNotExistsAsync método.

Observação

O CreateDatabaseIfNotExistsAsync método retorna um Task<ResourceResponse<Database>> objeto e o código de status da resposta pode ser verificado para determinar se um banco de dados foi criado ou um banco de dados existente foi retornado.

Criando uma coleção de documentos

Uma coleção de documentos é um contêiner para documentos JSON e pode ser criada no Portal do Azure ou programaticamente usando o DocumentClient.CreateDocumentCollectionIfNotExistsAsync método:

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

O CreateDocumentCollectionIfNotExistsAsync método requer dois argumentos obrigatórios – um nome de banco de dados especificado como um Uri, e um DocumentCollection objeto. O DocumentCollection objeto representa uma coleção de documentos cujo nome é especificado com a Id propriedade. O CreateDocumentCollectionIfNotExistsAsync método cria a coleção de documentos, se ela não existir, ou retorna a coleção de documentos, se ela já existir. No entanto, o aplicativo de exemplo ignora todos os dados retornados pelo CreateDocumentCollectionIfNotExistsAsync método.

Observação

O CreateDocumentCollectionIfNotExistsAsync método retorna um Task<ResourceResponse<DocumentCollection>> objeto e o código de status da resposta pode ser verificado para determinar se uma coleção de documentos foi criada ou se uma coleção de documentos existente foi retornada.

Opcionalmente, o CreateDocumentCollectionIfNotExistsAsync método também pode especificar um RequestOptions objeto, que encapsula opções que podem ser especificadas para solicitações emitidas para a conta do Azure Cosmos DB. A RequestOptions.OfferThroughput propriedade é usada para definir o nível de desempenho da coleção de documentos e, no aplicativo de exemplo, é definida como 400 unidades de solicitação por segundo. Esse valor deve ser aumentado ou diminuído dependendo se a coleção será acessada com ou sem frequência.

Importante

Observe que o CreateDocumentCollectionIfNotExistsAsync método criará uma nova coleção com uma taxa de transferência reservada, que tem implicações de preço.

Recuperando documentos de coleta de documentos

O conteúdo de uma coleção de documentos pode ser recuperado criando e executando uma consulta de documento. Uma consulta de documento é criada com o DocumentClient.CreateDocumentQuery método:

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

Essa consulta recupera de forma assíncrona todos os documentos da coleção especificada e coloca os documentos em uma List<TodoItem> coleção para exibição.

O CreateDocumentQuery<T> método especifica um Uri argumento que representa a coleção que deve ser consultada para documentos. Neste exemplo, a collectionLink variável é um campo de nível de classe que especifica o Uri que representa a coleção de documentos da qual recuperar documentos:

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

O CreateDocumentQuery<T> método cria uma consulta que é executada de forma síncrona e retorna um IQueryable<T> objeto. No entanto, o AsDocumentQuery método converte o IQueryable<T> objeto em um IDocumentQuery<T> objeto que pode ser executado de forma assíncrona. A consulta assíncrona é executada com o IDocumentQuery<T>.ExecuteNextAsync método, que recupera a próxima página de resultados do banco de dados de documentos, com a IDocumentQuery<T>.HasMoreResults propriedade indicando se há resultados adicionais a serem retornados da consulta.

Os documentos podem ser filtrados no lado do servidor incluindo uma Where cláusula na consulta, que aplica um predicado de filtragem à consulta em relação à coleção de documentos:

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

Essa consulta recupera todos os documentos da coleção cuja Done propriedade é igual a false.

Inserindo um documento em uma coleção de documentos

Os documentos são conteúdo JSON definido pelo usuário e podem ser inseridos em uma coleção de documentos com o DocumentClient.CreateDocumentAsync método:

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

O CreateDocumentAsync método especifica um Uri argumento que representa a coleção na qual o documento deve ser inserido e um object argumento que representa o documento a ser inserido.

Substituindo um documento em uma coleção de documentos

Os documentos podem ser substituídos em uma coleção de documentos com o DocumentClient.ReplaceDocumentAsync método:

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

O ReplaceDocumentAsync método especifica um Uri argumento que representa o documento na coleção que deve ser substituído e um object argumento que representa os dados atualizados do documento.

Excluindo um documento de uma coleção de documentos

Um documento pode ser excluído de uma coleção de documentos com o DocumentClient.DeleteDocumentAsync método:

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

O DeleteDocumentAsync método especifica um Uri argumento que representa o documento na coleção que deve ser excluído.

Excluindo uma coleção de documentos

Uma coleção de documentos pode ser excluída de um banco de dados com o DocumentClient.DeleteDocumentCollectionAsync método:

await client.DeleteDocumentCollectionAsync(collectionLink);

O DeleteDocumentCollectionAsync método especifica um Uri argumento que representa a coleção de documentos a ser excluída. Observe que invocar esse método também excluirá os documentos armazenados na coleção.

Excluindo um banco de dados

Um banco de dados pode ser excluído de uma conta de banco de dados do Azure Cosmos DB com o DocumentClient.DeleteDatabaesAsync método:

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

O DeleteDatabaseAsync método especifica um Uri argumento que representa o banco de dados a ser excluído. Observe que invocar esse método também excluirá as coleções de documentos armazenadas no banco de dados e os documentos armazenados nas coleções de documentos.

Resumo

Este artigo explicou como usar a biblioteca de cliente do Azure Cosmos DB .NET Standard para integrar um banco de dados de documentos do Azure Cosmos DB em um Xamarin.Forms aplicativo. Um banco de dados de documentos do Azure Cosmos DB é um banco de dados NoSQL que fornece acesso de baixa latência a documentos JSON, oferecendo um serviço de banco de dados rápido, altamente disponível e escalável para aplicativos que exigem escala perfeita e replicação global.