Quickstart: Construir uma aplicação de .NET Framework ou Core utilizando a conta API API AZure Cosmos DB Gremlin

APLICA-SE A: Gremlin API

O Azure Cosmos DB é um serviço de bases de dados com vários modelos e distribuído globalmente da Microsoft. Pode criar e consultar rapidamente o documento, a chave/valor e as bases de dados de gráficos, que beneficiam de capacidades de escalamento horizontal e distribuição global no centro do Azure Cosmos DB.

Este quickstart demonstra como criar uma conta API AZure Cosmos DB Gremlin, base de dados e gráfico (recipiente) utilizando o portal Azure. Em seguida, irá criar e executar uma aplicação de consola com o controlador open-source Gremlin.Net.

Pré-requisitos

Se ainda não tiver Visual Studio 2019 instalado, pode baixar e utilizar o Visual Studio edição comunitária de 2019. Confirme que ativa o desenvolvimento do Azure durante a configuração do Visual Studio.

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

Criar uma conta de base de dados

  1. Numa nova janela do browser, inicie sessão no portal do Azure.

  2. No menu esquerdo, selecione Criar um recurso.

    Criar um recurso no portal do Azure

  3. Na página Nova, selecione Databases > Azure Cosmos DB.

    O painel Bases de dados do portal do Azure

  4. Na página De Conta DB Create Azure Cosmos, insira as definições para a nova conta DB da Azure Cosmos.

    Definição Valor Descrição
    Subscrição Nome da subscrição Selecione a subscrição do Azure que quer utilizar para esta conta do Azure Cosmos.
    Grupo de Recursos Nome do grupo de recursos Selecione um grupo de recursos ou selecione Criar novo e, em seguida, introduza um nome exclusivo para o novo grupo de recursos.
    Nome da Conta Introduza um nome exclusivo Introduza um nome exclusivo para identificar a sua conta do Azure Cosmos DB. A sua conta URI será gremlin.azure.com anexada ao seu nome de conta único.

    O nome da conta só pode usar letras minúsculas, números e hífens (-), e deve ter entre 3 e 44 caracteres de comprimento.
    API Gremlin (grafo) A API determina o tipo de conta a criar. A Azure Cosmos DB fornece cinco APIs: Core (SQL) para bases de dados de documentos, Gremlin para bases de dados de gráficos, MongoDB para bases de dados de documentos, Tabela Azure e Cassandra. Deve criar uma conta separada para cada API.

    Selecione Gremlin (gráfico), porque neste arranque rápido está a criar uma tabela que funciona com a API de Gremlin.

    Saiba mais sobre a API de Gremlin.
    Localização A região mais próxima dos seus utilizadores Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o acesso mais rápido aos dados.
    Modo de capacidade Produção provisida ou sem servidor Selecione Provisão para criar uma conta no modo de produção previsto. Selecione Serverless para criar uma conta no modo sem servidor.
    Aplicar desconto de nível gratuito Azure Cosmos DB Aplicar ou não aplicar Com o nível livre Azure Cosmos DB, você receberá os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente numa conta. Saiba mais sobre o free tier.

    Nota

    Pode ter até uma conta DB Azure Cosmos de nível gratuito por subscrição Azure e deve optar pela criação da conta. Se não vir a opção de aplicar o desconto de nível livre, isto significa que outra conta na subscrição já foi ativada com nível gratuito.

    A página de nova conta do Azure Cosmos DB

  5. No separador Distribuição Global, configuure os seguintes detalhes. Pode deixar os valores predefinidos para efeitos deste arranque rápido:

    Definição Valor Descrição
    Redundância Geográfica Desativar Ativar ou desativar a distribuição global na sua conta, emparelhando a sua região com uma região de pares. Pode adicionar mais regiões à sua conta mais tarde.
    Escritas de várias regiões Desativar A capacidade de escrita multi-região permite-lhe tirar partido da produção prevista para as suas bases de dados e contentores em todo o mundo.

    Nota

    As seguintes opções não estão disponíveis se selecionar Serverless como o modo Capacidade:

    • Aplicar Desconto de Escalão Gratuito
    • Georredundância
    • Escritas de várias regiões
  6. Opcionalmente, pode configurar detalhes adicionais nos seguintes separadores:

    • Networking - Configurar o acesso a partir de uma rede virtual.
    • Política de Backup - Configurar uma política de backup periódica ou contínua.
    • Encriptação - Utilize uma chave gerida pelo serviço ou uma chave gerida pelo cliente.
    • Tags - Tags são pares de nome/valor que lhe permitem categorizar recursos e visualizar faturação consolidada aplicando a mesma etiqueta a múltiplos recursos e grupos de recursos.
  7. Selecione Rever + criar.

  8. A criação da conta demora alguns minutos. Espere que o portal exiba os Parabéns! A sua conta DB Azure Cosmos foi criada página.

    Página criada por Azure Cosmos DB

Adicionar um grafo

Agora, pode utilizar a ferramenta Data Explorer no portal do Azure para criar uma base de dados de gráfico.

  1. Selecione Data Explorer > New Graph.

    A área Adicionar Gráfico é apresentada na extremidade direita, pelo que poderá ter de se deslocar para a direita para vê-la.

    O Data Explorer do portal do Azure, página Adicionar Gráfico

  2. Na página Adicionar gráfico, introduza as definições para o novo gráfico.

    Definição Valor sugerido Descrição
    ID da base de dados base de dados de exemplo Dê o nome sample-database à nova base de dados. Os nomes das bases de dados têm de ter entre um e 255 carateres e não podem conter / \ # ? nem espaços à direita.
    Débito 400 RUs Altere o débito para 400 unidades de pedido por segundo (RU/s). Se pretender reduzir a latência, pode aumentar verticalmente o débito mais tarde.
    ID do Graph gráfico de exemplo Dê o nome sample-graph à nova coleção. Os nomes dos gráficos têm os mesmos requisitos de carateres que os IDs das bases de dados.
    Chave de Partição /pk Todas as contas da Cosmos DB precisam de uma chave de partição para a escala horizontal. Saiba como selecionar uma chave de partição apropriada no artigo de partição de dados Graph.
  3. Uma vez preenchido o formulário, selecione OK.

Clonar a aplicação de exemplo

Agora vamos clonar uma aplicação da API do Gremlin a partir do GitHub, definir a cadeia de ligação e executá-la. Vai ver como é fácil trabalhar com dados programaticamente.

  1. Abra uma linha de comandos, crie uma nova pasta designada git-samples e, em seguida, feche a linha de comandos.

    md "C:\git-samples"
    
  2. Abra uma janela de terminal do git, como o git bash e utilize o comando cd para alterar para uma nova pasta e instalar a aplicação de exemplo.

    cd "C:\git-samples"
    
  3. Execute o seguinte comando para clonar o repositório de exemplo. Este comando cria uma cópia da aplicação de exemplo no seu computador.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
    
  4. Em seguida, abra o Visual Studio e o ficheiro da solução.

  5. Restaure os pacotes NuGet no projeto. Isto deve incluir o controlador Gremlin.Net, bem como o pacote Newtonsoft.Json.

  6. Também pode instalar o Gremlin.Net@v3.4.6 controlador manualmente utilizando o gestor de pacotes Nuget ou o utilitário da linha de comando nuget:

    nuget install Gremlin.NET -Version 3.4.6
    

Nota

Atualmente, a API gremlin apenas suporta Gremlin.Net até v3.4.6. Se instalar a versão mais recente, receberá erros ao utilizar o serviço.

Rever o código

Este passo é opcional. Se estiver interessado em aprender de que forma os recursos da base de dados são criados no código, pode consultar os seguintes fragmentos. Caso contrário, pode avançar diretamente para Update your connection string (Atualizar a cadeia de ligação).

Os seguintes fragmentos são retirados do ficheiro Program.cs.

  • Desaça os parâmetros de ligação com base na conta acima criada:

    private static string Host => Environment.GetEnvironmentVariable("Host") ?? throw new ArgumentException("Missing env var: Host");
    private static string PrimaryKey => Environment.GetEnvironmentVariable("PrimaryKey") ?? throw new ArgumentException("Missing env var: PrimaryKey");
    private static string Database => Environment.GetEnvironmentVariable("DatabaseName") ?? throw new ArgumentException("Missing env var: DatabaseName");
    private static string Container => Environment.GetEnvironmentVariable("ContainerName") ?? throw new ArgumentException("Missing env var: ContainerName");
    
    private static bool EnableSSL
    {
        get
        {
            if (Environment.GetEnvironmentVariable("EnableSSL") == null)
            {
                return true;
            }
    
            if (!bool.TryParse(Environment.GetEnvironmentVariable("EnableSSL"), out bool value))
            {
                throw new ArgumentException("Invalid env var: EnableSSL is not a boolean");
            }
    
            return value;
        }
    }
    
    private static int Port
    {
        get
        {
            if (Environment.GetEnvironmentVariable("Port") == null)
            {
                return 443;
            }
    
            if (!int.TryParse(Environment.GetEnvironmentVariable("Port"), out int port))
            {
                throw new ArgumentException("Invalid env var: Port is not an integer");
            }
    
            return port;
        } 
    }
    
  • Os comandos gremlin a serem executados estão listados num Dicionário:

    private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
    {
        { "Cleanup",        "g.V().drop()" },
        { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
        { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
        { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
        { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
        { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
        { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
        { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
        { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
        { "CountVertices",  "g.V().count()" },
        { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
        { "Project",        "g.V().hasLabel('person').values('firstName')" },
        { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
        { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
        { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
        { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
        { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
        { "CountEdges",     "g.E().count()" },
        { "DropVertex",     "g.V('thomas').drop()" },
    };
    
  • Criar um objeto novo GremlinServer e GremlinClient de ligação utilizando os parâmetros acima indicados:

    string containerLink = "/dbs/" + Database + "/colls/" + Container;
    Console.WriteLine($"Connecting to: host: {Host}, port: {Port}, container: {containerLink}, ssl: {EnableSSL}");
    var gremlinServer = new GremlinServer(Host, Port, enableSsl: EnableSSL, 
                                            username: containerLink, 
                                            password: PrimaryKey);
    
    ConnectionPoolSettings connectionPoolSettings = new ConnectionPoolSettings()
    {
        MaxInProcessPerConnection = 10,
        PoolSize = 30, 
        ReconnectionAttempts= 3,
        ReconnectionBaseDelay = TimeSpan.FromMilliseconds(500)
    };
    
    var webSocketConfiguration =
        new Action<ClientWebSocketOptions>(options =>
        {
            options.KeepAliveInterval = TimeSpan.FromSeconds(10);
        });
    
    
    using (var gremlinClient = new GremlinClient(
        gremlinServer, 
        new GraphSON2Reader(), 
        new GraphSON2Writer(), 
        GremlinClient.GraphSON2MimeType, 
        connectionPoolSettings, 
        webSocketConfiguration))
    {
    
  • Execute cada consulta gremlin usando o GremlinClient objeto com uma tarefa assídua. Pode ler as consultas de Gremlin a partir do dicionário definido no passo anterior e executá-las. Mais tarde obtenha o resultado e leia os valores, que são formatados como um dicionário, usando a JsonSerializer classe de Newtonsoft.Jsem pacote:

    foreach (var query in gremlinQueries)
    {
        Console.WriteLine(String.Format("Running this query: {0}: {1}", query.Key, query.Value));
    
        // Create async task to execute the Gremlin query.
        var resultSet = SubmitRequest(gremlinClient, query).Result;
        if (resultSet.Count > 0)
        {
            Console.WriteLine("\tResult:");
            foreach (var result in resultSet)
            {
                // The vertex results are formed as Dictionaries with a nested dictionary for their properties
                string output = JsonConvert.SerializeObject(result);
                Console.WriteLine($"\t{output}");
            }
            Console.WriteLine();
        }
    
        // Print the status attributes for the result set.
        // This includes the following:
        //  x-ms-status-code            : This is the sub-status code which is specific to Cosmos DB.
        //  x-ms-total-request-charge   : The total request units charged for processing a request.
        //  x-ms-total-server-time-ms   : The total time executing processing the request on the server.
        PrintStatusAttributes(resultSet.StatusAttributes);
        Console.WriteLine();
    }
    

Atualizar a cadeia de ligação

Agora, regresse ao portal do Azure para obter as informações da cadeia de ligação e copie-as para a aplicação.

  1. A partir do portal do Azure, navegue até à sua conta da base de dados de gráficos. No separador Descrição geral, pode ver dois pontos finais-

    .NET SDK URI - Este valor é utilizado quando se liga à conta de gráfico utilizando a biblioteca Microsoft.Azure.Graphs.

    Ponto final do Gremlin – Este valor é utilizado quando se liga à conta de gráficos através da biblioteca de Gremlin.Net.

    Copiar o ponto final

    Para executar esta amostra, copie o valor gremlin Endpoint, elimine o número de porta no final, ou seja, o URI torna-se https://<your cosmos db account name>.gremlin.cosmosdb.azure.com . O valor do ponto final deve parecer testgraphacct.gremlin.cosmosdb.azure.com

  2. Em seguida, navegue no separador Chaves e copie o valor KEY PRINCIPAL a partir do portal Azure.

  3. Depois de copiar o URI e a CHAVE PRIMÁRIA da sua conta, guarde-os para uma nova variável ambiental na máquina local que executa a aplicação. Para definir a variável ambiente, abra uma janela de ordem de comando e execute o seguinte comando. Certifique-se de que substitui os valores <Your_Azure_Cosmos_account_URI> e <Your_Azure_Cosmos_account_PRIMARY_KEY>.

    setx Host "<your Azure Cosmos account name>.gremlin.cosmosdb.azure.com"
    setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"
    
  4. Abra o ficheiro .cs Programa e atualize as variáveis "base de dados e contentores" com os nomes da base de dados e do recipiente (que também é o nome do gráfico) criado acima.

    private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";

  5. Guarde o ficheiro Program.cs.

Atualizou agora a sua aplicação com todas as informações necessárias para comunicar com o Azure Cosmos DB.

Executar a aplicação de consola

Clique em CTRL + F5 para executar a aplicação. A aplicação irá imprimir os comandos de consulta Gremlin e os resultados na consola.

A janela de consola apresenta os vértices e as margens a adicionar ao gráfico. Quando o script tiver concluído, prima ENTER para fechar a janela da consola.

Utilizar o Data Explorer para pesquisar

Agora, pode voltar ao Data Explorer no portal do Azure e procurar e consultar os dados do gráfico novo.

  1. No Data Explorer, a nova base de dados é apresentada no painel Gráficos. Expanda a base de dados e os nós do contentor e, em seguida, clique em Gráfico.

  2. Clique no botão Aplicar Filtro para utilizar a consulta predefinida para ver todos os vértices no gráfico. Os dados gerados pela aplicação de exemplo são apresentados no painel Gráficos.

    Pode ampliar e reduzir o gráfico, expandir o espaço de visualização do gráfico, adicionar mais vértices e mover vértices na superfície de visualização.

    Ver o gráfico no Data Explorer no portal do Azure

Rever os SLAs no portal do Azure

O portal Azure monitoriza a sua conta Cosmos DB, armazenamento, disponibilidade, latência e consistência. Gráficos para métricas associadas a um Acordo de Nível de Serviço DB da Azure Cosmos (SLA) mostram o valor SLA em comparação com o desempenho real. Este conjunto de métricas torna transparente a monitorização dos seus SLAs.

Para rever métricas e SLAs:

  1. Selecione Métricas no menu de navegação da sua conta Cosmos DB.

  2. Selecione um separador como Latência e selecione um prazo à direita. Compare as linhas Atual e SLA nas tabelas.

    Conjunto de métricas do Azure Cosmos DB

  3. Reveja as métricas nas outras abas.

Limpar os recursos

Quando terminar a sua app e a conta DB da Azure Cosmos, pode apagar os recursos Azure que criou para não incorrer em mais encargos. Para eliminar os recursos:

  1. Na barra de pesquisa do portal Azure, procure e selecione grupos de Recursos.

  2. A partir da lista, selecione o grupo de recursos que criou para este arranque rápido.

    Selecione o grupo de recursos para eliminar

  3. Na página de visão geral do grupo de recursos, selecione Eliminar o grupo de recursos.

    Eliminar o grupo de recursos

  4. Na janela seguinte, insira o nome do grupo de recursos para eliminar e, em seguida, selecione Delete.

Passos seguintes

Neste guia rápido, aprendeu a criar uma conta do Azure Cosmos DB, a criar um gráfico com o Data Explorer e a executar uma aplicação. Agora, pode criar consultas mais complexas e implementar lógica poderosa para percorrer gráficos com Gremlin.

Query using Gremlin (Utilizar Gremlin para consultar)