Azure DocumentDB: visão geral e primeiros passos

O objetivo deste artigo é apresentar uma visão geral do DocumentDB, assim como os primeiros passos para que esta solução NoSQL que integra o Microsoft Azure possa ser utilizada por desenvolvedores .NET.

Introdução

Proposto por Edgar F. Codd ainda na década de 1970, o modelo relacional revolucionou a forma como as organizações manipulam seus dados. Ainda hoje esta abordagem segue bastante popular no ambiente corporativo, com destaque para o Microsoft SQL Server e o Oracle Database como principais soluções no que se refere a sistemas gerenciadores de bancos de dados relacionais (SGBDRs).

Tabelas, colunas e registros são estruturas típicas deste tipo de tecnologia. A linguagem SQL (Structured Query Language) é outro padrão adotado dentro do mundo relacional, o que diminui em muitos casos a curva de aprendizado ao se migrar de um produto para outro.

Apesar de seguir como a opção ideal para um grande número de cenários, o modelo relacional apresenta limitações em algumas situações mais específicas:

• Questões como disponibilidade e escalabilidade constituem bons exemplos disto, já que acabam por esbarrar em restrições de hardware. É sempre bom ressaltar que máquinas utilizadas como servidores não possuem uma capacidade de expansão infinita;
• Agrupamentos de dados mais complexos costumam gerar problemas em termos de modelagem, resultando muitas vezes em uma estruturação mais complexa e que pode requerer maiores esforços durante atividades futuras de manutenção;
• Outra dificuldade frequente está em conciliar as representações em memória (objetos) nas aplicações com o equivalente numa base relacional. Uma instância de uma classe nem sempre corresponderá à forma como os dados dos quais depende se encontram organizados em tabelas e colunas. Este conflito é conhecido como "impedance mismatch".

Uma alternativa ao padrão relacional seria o modelo NoSQL (“Not only SQL”). Existem diversas soluções deste gênero hoje no mercado, sendo características comuns à maioria destes produtos preocupações quanto à garantia de uma alta disponibilidade, escalabilidade facilitada e flexibilidade. Bancos de dados orientados a documentos estão entra as opções NoSQL mais populares, sendo o Azure DocumentDB e o MongoDB bons exemplos deste tipo de implementação.

Este artigo tem por meta apresentar as principais características do DocumentDB, um serviço NoSQL que integra o Microsoft Azure. Será demonstrada ainda a criação de uma conta para acesso a este recurso na nuvem, bem como um exemplo simples de utilização do mesmo em uma aplicação .NET.

Azure DocumentDB: uma visão geral

O Azure DocumentDB é um serviço de banco de dados NoSQL orientado a documentos e situado na nuvem, conforme já mencionado anteriormente. Mas, do ponto de vista prático, o que significa uma solução deste gênero ser orientada a documentos?

Um documento corresponde à unidade básica de representação neste tipo de tecnologia, com uma função próxima àquela desempenhada pelos registros em tabelas relacionais. Contudo, é justamente neste ponto que começam as diferenças entre estas duas abordagens (documentos x relacional).

Ao contrário das colunas pré-definidas que existem em uma tabela convencional, um documento conta com uma estrutura flexível. Devido a este aspecto um banco de dados orientado a documentos é classificado como “schemaless”, ou seja, não possui um esquema rígido (característica esta típica do modelo relacional).

Muitas das alternativas baseadas em documentos empregam o padrão JSON (JavaScript Object Notation) para o armazenamento de dados. O próprio DocumentDB não foge a esta tendência.

Na figura a seguir está um exemplo de um documento representado no padrão JSON:

A comunicação com uma base do DocumentDB acontece via protocolo HTTP, utilizando para isto o modelo REST (Representational State Transfer). A Microsoft disponibiliza SDKs para plataformas .NET, Node.js, Java e Python; outras alternativas de desenvolvimento que não dispõem deste recurso podem fazer uso do Azure DocumentDB REST API, a fim de viabilizar o acesso e manipulação de bases do DocumentDB.

Outras características a ressaltar do Azure DocumentDB são:

• Sua escalabilidade, o que inclui a capacidade de atender a milhões de requisições por segundo;
• A possibilidade de uso de transações baseadas no padrão ACID (prática esta bastante comum em produtos que seguem o paradigma relacional);
• O suporte a dados geoespaciais;
• A execução de consultas utilizando expressões SQL ou LINQ;
• A cobrança tomando por base o número de requisições e o uso de storage.

Como o DocumentDB está estruturado?

Na próxima imagem é possível observar como o DocumentDB encontra-se estruturado na nuvem:

Uma conta de acesso (DocumentDB Account) possibilita a administração de vários bancos de dados. Cada base, por sua vez, está vinculada a uma única conta do DocumentDB. Usuários e permissões podem ser definidos por banco.

Um banco de dados do DocumentDB possuirá uma ou mais coleções. Já uma coleção é um agrupamento de documentos JSON, apresentando uma função similar à de uma tabela em uma base relacional.

Attachments (anexos) podem estar vinculados a documentos, apontando para referências externas (blob/media). O gerenciamento de um attachment pode ficar a cargo do próprio DocumentDB ou ainda, ocorrer via providers como OneDrive e DropBox.

Stored procedures, triggers e user defined functions (UDFs) podem ser criadas em um banco de dados do DocumentDB, possuindo um comportamento similar ao das estruturas equivalentes de uma base relacional. A codificação destas estruturas acontece por meio de instruções implementadas em JavaScript.

Criando uma conta de acesso ao DocumentDB

Para criar uma nova conta do DocumentDB será necessário acessar inicialmente o portal do Microsoft Azure:

https://portal.azure.com/

Após a autenticação acionar o item Novo, na sequência a opção Dados + Armazenamento e, por fim, Azure DocumentDB:

Aparecerá neste momento uma tela (como indicado na próxima imagem) para a configuração de uma nova conta:

• No campo ID foi informado o valor documentdbtnwiki;
• Selecionar a criação de um novo grupo de recursos, especificando como nome do mesmo TesteDocumentDB.

Preenchidas estas definições acionar a opção Criar. Acessando a opção Todos os recursos, após alguns segundos, será possível constatar a presença do recurso TesteDocumentDB:

Ao acessar o grupo TesteDocumentDB será exibido um painel no qual estará listado o banco documentdbtnwiki:

Utilizando o DocumentDB em uma aplicação .NET

O uso do DocumentDB em uma aplicação depende de uma URI (baseada no ID informado para a conta), bem como de uma chave primária de acesso. Estas definições podem ser obtidas a partir de 2 caminhos assinalados no painel apresentado a seguir, em que é possível visualizar as propriedades do banco documentdbtnwiki:
**

** 
Na próxima imagem estão destacadas em vermelho tais configurações:

O recomendável é que estes valores sejam armazenados no arquivo .config de uma aplicação, como indicado no seguinte exemplo:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="URIExemplo"
         value="ENDEREÇO_URI" />
    <add key="PKExemplo"
         value="CHAVE_PRIMÁRIA" />
  </appSettings>
 
  ...  
 
</configuration>

Além disso será necessário adicionar via NuGet o package Microsoft.Azure.DocumentDB ao projeto:

Além da biblioteca que viabiliza o acesso ao DocumentDB, esta ação também fará com que seja incluído no projeto o pacote Newtonsoft.Json:

Na listagem a seguir está o código que permitirá a criação de um novo banco do DocumentDB em uma aplicação .NET:

• Será por meio de uma instância da classe DocumentClient (namespace Microsoft.Azure.Documents.Client) que acontecerá a comunicação com o serviço NoSQL na nuvem. Este tipo recebe como parâmetros a URI obtida a partir do portal do Azure, além da chave primária associada a uma conta do DocumentDB;
• Ao se invocar o método CreateDatabaseAsync da referência de DocumentClient será informada uma instância do tipo Database (namespace Microsoft.Azure.Documents), cuja propriedade Id foi preenchida com o valor BaseExemplo. Esta ação fará com que o banco BaseExemplo seja gerado de forma assíncrona e vinculado à conta criada anteriormente.

...
 
string endpointUri =
    ConfigurationManager.AppSettings["URIExemplo"];
string primaryKey =
    ConfigurationManager.AppSettings["PKExemplo"];
 
DocumentClient client = new  DocumentClient(
    new Uri(endpointUri), primaryKey);
 
await client.CreateDatabaseAsync(
    new Database { Id = "BaseExemplo" });
 
...

O próximo passo consiste na criação de uma coleção chamada Catalogo, a qual armazenará informações sobre itens (produtos e serviços) comercializados por uma companhia:

• Aqui também será utilizada uma instância do tipo DocumentClient, com a mesma servindo de base para a comunicação com o banco criado na etapa anterior;
• Uma referência da classe DocumentCollection (namespace Microsoft.Azure.Documents) será gerada na sequência. Na propriedade Id foi definido o nome da coleção; já em IndexingPolicy será atribuído um objeto baseado no tipo de mesmo nome (localizado no namespace Microsoft.Azure.Documents), o qual receberá uma instância de RangeIndex (namespace Microsoft.Azure.Documents) que contém uma regra para a consulta de valores de texto empregando substrings;
• Por fim, será invocado o método CreateDocumentCollectionAsync a partir da referência de DocumentClient. Esta operação receberá como parâmetros uma URI para acesso à base gerada (via método CreateDatabaseUri da classe UriFactory – namespace Microsoft.Azure.Documents.Client), o próprio objeto contendo as definições da coleção e uma instância de RequestOptions (namespace Microsoft.Azure.Documents.Client) na qual se indicou por meio da propriedade OfferThroughput o limite mínimo número de requisições por segundo (para efeitos de cobrança).

...
 
DocumentClient client = new  DocumentClient(
    new Uri(endpointUri), primaryKey);
 
DocumentCollection collectionInfo = new  DocumentCollection();
collectionInfo.Id = "Catalogo";
 
collectionInfo.IndexingPolicy =
    new IndexingPolicy(new RangeIndex(DataType.String) { Precision = -1 });
 
await client.CreateDocumentCollectionAsync(
    UriFactory.CreateDatabaseUri("BaseExemplo"),
    collectionInfo,
    new RequestOptions { OfferThroughput = 400 });
 
...

Voltando ao portal do Azure será possível notar que o banco BaseExemplo foi criado, assim como já existe uma coleção vinculada ao mesmo:

Já em BaseExemplo será listada a coleção Catalogo:

Como aconteceu nos exemplos anteriores, a inclusão também dependerá do uso de uma instância de DocumentClient:

• Um objeto anônimo está sendo gerado e associado à variável serv003. Esta instância representa o documento que será incluído na coleção Catalogo;
• O método CreateDocumentAsync de DocumentClient será invocado, recebendo como parâmetros uma URI indicando a coleção que receberá um novo documento (via método estático CreateDocumentCollectionUri da classe UriFactory) e o documento para inclusão na base de dados.

...
 
var serv003 = new
{
    id = "SERV003",
    Nome = "MANUTENCAO ELETRICA",
    ValorHora = 200.00
};
 
DocumentClient client = new  DocumentClient(
    new Uri(endpointUri), primaryKey);
 
await client.CreateDocumentAsync(
    UriFactory.CreateDocumentCollectionUri(
        "BaseExemplo", "Catalogo"), serv003);
 
...

Após a execução deste último trecho de código acionar a coleção Catalogo no Portal de Azure. Uma das opções disponíveis é Gerenciador de Consultas, funcionalidade esta que permite o acesso a dados cadastrados em uma coleção através de expressões SQL:

O Gerenciador de Consultas já trará por default uma query, conforme exibido na próxima imagem:

Ao ser executada esta consulta trará como resultado o documento gerado pela última sequência de código:

Conclusão

Baseado no conceito de documento e no formato JSON, o Azure DocumentDB é uma solução NoSQL bastante flexível e escalável oferecida a partir da nuvem da Microsoft. Além de contar com SDKs compatíveis com aplicações implementadas em .NET, Node.js, Java e Python, o DocumentDB também pode ser acessado via API REST por qualquer plataforma capaz de realizar este tipo de comunicação. Outro diferencial desta solução que merece ser destacado está na possibilidade de uso de expressões SQL para a consulta a informações em um banco de dados.

Referências

DocumentDB documentation
https://azure.microsoft.com/en-us/documentation/services/documentdb/