Início Rápido: Criar um aplicativo Node.js usando a conta de API do Gremlin do Azure Cosmos DBQuickstart: Build a Node.js application by using Azure Cosmos DB Gremlin API account

O Azure Cosmos DB é o serviço de banco de dados multi-modelo distribuído globalmente da Microsoft.Azure Cosmos DB is the globally distributed multimodel database service from Microsoft. É possível criar e consultar rapidamente documentos, chave/valor e bancos de dados do grafo. Todos se beneficiam de recursos de escala horizontal e distribuição global no núcleo do Azure Cosmos DB.You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Este início rápido demonstra como criar uma conta de API do Gremlin do Azure Cosmos DB, um banco de dados e um grafo usando o portal do Azure.This quickstart demonstrates how to create an Azure Cosmos DB Gremlin API account, database, and graph using the Azure portal. Em seguida, você compila e executa um aplicativo de console usando o driver Gremlin Node.js de software livre.You then build and run a console app by using the open-source Gremlin Node.js driver.

Pré-requisitosPrerequisites

Antes que possa executar esta amostra, você deverá ter os seguintes pré-requisitos:Before you can run this sample, you must have the following prerequisites:

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.If you don't have an Azure subscription, create a free account before you begin.

Criar uma conta de banco de dadosCreate a database account

  1. Em uma nova janela do navegador, entre no Portal do Azure.In a new browser window, sign in to the Azure portal.

  2. Clique em Criar um recurso > Bancos de dados > Azure Cosmos DB.Click Create a resource > Databases > Azure Cosmos DB.

    Painel “Bancos de dados” do portal do Azure

  3. Na página Criar Conta do Azure Cosmos DB, insira as configurações da nova conta do Azure Cosmos DB.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    ConfiguraçãoSetting ValorValue DESCRIÇÃODescription
    AssinaturaSubscription Sua assinaturaYour subscription Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupo de recursosResource Group Criar NovoCreate new

    Em seguida, insira o mesmo nome exclusivo fornecido na IDThen enter the same unique name as provided in ID
    Selecione Criar novo.Select Create new. Insira o novo nome do grupo de recursos para sua conta.Then enter a new resource-group name for your account. Para simplificar, use um nome igual à sua ID.For simplicity, use the same name as your ID.
    Nome da contaAccount Name Insira um nome exclusivoEnter a unique name Insira um nome exclusivo para identificar a conta do Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. Como documents.Azure.com é acrescentado à ID que você fornece para criar o URI, use uma ID exclusiva.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    A ID deve conter apenas letras minúsculas, números e o caractere de hífen (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. Ela precisa ter entre 3 e 31 caracteres.It must be between 3 and 31 characters in length.
    APIAPI Gremlin (grafo)Gremlin (graph) A API determina o tipo de conta a ser criada.The API determines the type of account to create. O Azure Cosmos DB fornece cinco APIs: Core(SQL) para bancos de dados de documentos, Gremlin para o bancos de dados de grafos, MongoDB para bancos de dados de documentos, Tabela do Azure e Cassandra.Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. No momento, você deve criar uma conta separada para cada API.Currently, you must create a separate account for each API.

    Selecione Gremlin (grafo) porque neste guia de início rápido você está criando uma tabela que funciona com a API do Gremlin.Select Gremlin (graph) because in this quickstart you are creating a table that works with the Gremlin API.

    Saiba mais sobre a API do Graph.Learn more about the Graph API.
    Local padrãoLocation Selecione a região mais próxima de seus usuáriosSelect the region closest to your users Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use o local mais próximo dos usuários para fornecer a eles acesso mais rápido aos dados.Use the location that's closest to your users to give them the fastest access to the data.

    Selecione Revisar + Criar.Select Review+Create. Você pode ignorar as seções Rede e Marcas.You can skip the Network and Tags section.

    A folha da nova conta do Azure Cosmos DB

  4. A criação da conta leva alguns minutos.The account creation takes a few minutes. Aguarde até que o portal exiba a página Parabéns! Sua conta do Azure Cosmos DB foi criada.Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created page.

    O painel Notificações do portal do Azure

Adicionar um grafoAdd a graph

Agora, você pode usar a ferramenta Data Explorer no portal do Azure para criar um banco de dados de grafo.You can now use the Data Explorer tool in the Azure portal to create a graph database.

  1. Clique em Data Explorer > Novo Grafo.Click Data Explorer > New Graph.

    A área Adicionar Grafo é exibida à direita, talvez seja necessário rolar para a direita para vê-la.The Add Graph area is displayed on the far right, you may need to scroll right to see it.

    O Data Explorer do Portal do Azure, página Adicionar Grafo

  2. Na página Adicionar Grafo, insira as configurações do novo grafo.In the Add graph page, enter the settings for the new graph.

    ConfiguraçãoSetting Valor sugeridoSuggested value DESCRIÇÃODescription
    ID do banco de dadosDatabase ID banco de dados de exemplosample-database Digite banco de dados de exemplo como o nome do novo banco de dados.Enter sample-database as the name for the new database. Os nomes de banco de dados devem ter entre um e 255 caracteres e não podem conter / \ # ? nem espaços à direita.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    ProdutividadeThroughput 400 RUs400 RUs Altere a taxa de transferência para 400 unidades de solicitação por segundo (RU/s).Change the throughput to 400 request units per second (RU/s). Se quiser reduzir a latência, você poderá escalar verticalmente a taxa de transferência mais tarde.If you want to reduce latency, you can scale up the throughput later.
    ID do GrafoGraph ID grafo de exemplosample-graph Digite grafo de exemplo como o nome da nova coleção.Enter sample-graph as the name for your new collection. Os nomes de grafo têm os mesmos requisitos de caractere do que as IDs de banco de dados.Graph names have the same character requirements as database IDs.
    Chave de partiçãoPartition Key /pk/pk Todas as contas do Cosmos DB precisam de uma chave de partição para dimensionar horizontalmente.All Cosmos DB accounts need a partition key to horizontally scale. Saiba como selecionar uma chave de partição apropriada no artigo de Particionamento de Dados de Grafo.Learn how to select an appropriate partition key in the Graph Data Partitioning article.
  3. Quando o formulário estiver preenchido, clique em OK.Once the form is filled out, click OK.

Clonar o aplicativo de exemploClone the sample application

Agora vamos clonar um aplicativo de API do Gremlin do GitHub, definir a cadeia de conexão e executá-lo.Now let's clone a Gremlin API app from GitHub, set the connection string, and run it. Você verá como é fácil trabalhar usando dados de forma programática.You'll see how easy it is to work with data programmatically.

  1. Abra um prompt de comando, crie uma nova pasta chamada exemplos de git e feche o prompt de comando.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. Abra uma janela de terminal de git, como git bash, e use o comando cd para alterar para a nova pasta para instalar o aplicativo de exemplo.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. Execute o comando a seguir para clonar o repositório de exemplo.Run the following command to clone the sample repository. Este comando cria uma cópia do aplicativo de exemplo no seu computador.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-nodejs-getting-started.git
    
  4. Abra o arquivo da solução no Visual Studio.Open the solution file in Visual Studio.

Examine o códigoReview the code

Esta etapa é opcional.This step is optional. Se você estiver interessado em aprender como os recursos de banco de dados são criados no código, poderá examinar os snippets de código a seguir.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Caso contrário, você poderá pular para Atualizar sua cadeia de conexão.Otherwise, you can skip ahead to Update your connection string.

Todos os snippets de código a seguir são retirados do arquivo app.js.The following snippets are all taken from the app.js file.

  • O cliente Gremlin é criado.The Gremlin client is created.

    const authenticator = new Gremlin.driver.auth.PlainTextSaslAuthenticator(
        `/dbs/${config.database}/colls/${config.collection}`, 
        config.primaryKey
    )
    
    
    const client = new Gremlin.driver.Client(
        config.endpoint, 
        { 
            authenticator,
            traversalsource : "g",
            rejectUnauthorized : true,
            mimeType : "application/vnd.gremlin-v2.0+json"
        }
    );
    
    

    Todas as configurações estão em config.js e podem ser editadas na seção a seguir.The configurations are all in config.js, which we edit in the following section.

  • Uma série de funções são definidas para executar operações de Gremlin diferentes.A series of functions are defined to execute different Gremlin operations. Este é um deles:This is one of them:

    function addVertex1()
    {
        console.log('Running Add Vertex1'); 
        return client.submit("g.addV(label).property('id', id).property('firstName', firstName).property('age', age).property('userid', userid).property('pk', 'pk')", {
                label:"person",
                id:"thomas",
                firstName:"Thomas",
                age:44, userid: 1
            }).then(function (result) {
                    console.log("Result: %s\n", JSON.stringify(result));
            });
    }
    
  • Cada função executa um client.execute método com um parâmetro de cadeia de caracteres de consulta Gremlin.Each function executes a client.execute method with a Gremlin query string parameter. Aqui está um exemplo de como g.V().count() é executado:Here is an example of how g.V().count() is executed:

    function countVertices()
    {
        console.log('Running Count');
        return client.submit("g.V().count()", { }).then(function (result) {
            console.log("Result: %s\n", JSON.stringify(result));
        });
    }
    
  • No final do arquivo, todos os métodos são então invocados.At the end of the file, all methods are then invoked. Isso irá executá-los um após o outro:This will execute them one after the other:

    client.open()
    .then(dropGraph)
    .then(addVertex1)
    .then(addVertex2)
    .then(addEdge)
    .then(countVertices)
    .catch((err) => {
        console.error("Error running query...");
        console.error(err)
    }).then((res) => {
        client.close();
        finish();
    }).catch((err) => 
        console.error("Fatal error:", err)
    );
    

Atualizar sua cadeia de conexãoUpdate your connection string

  1. Abra o arquivo config.js.Open the config.js file.

  2. Em config.js, preencha a config.endpoint chave com o valor Gremlin URI da página Visão geral do portal do Azure.In config.js, fill in the config.endpoint key with the Gremlin URI value from the Overview page of the Azure portal.

    config.endpoint = "https://<your_Gremlin_account_name>.gremlin.cosmosdb.azure.com:443/";

    Exibir e copiar uma chave de acesso no Portal do Azure, folha Chaves

  3. Em config.js, preencha o valor config.primaryKey com o valor Chave primária na página do portal do Azure Chaves.In config.js, fill in the config.primaryKey value with the Primary Key value from the Keys page of the Azure portal.

    config.primaryKey = "PRIMARYKEY";

    Folha “Chaves” do portal do Azure

  4. Insira o nome do banco de dados e o nome do grafo (contêiner) para o valor de config.database e config.collection.Enter the database name, and graph (container) name for the value of config.database and config.collection.

Aqui está um exemplo da aparência do seu arquivo config.js concluído:Here's an example of what your completed config.js file should look like:

var config = {}

// Note that this must not have HTTPS or the port number
config.endpoint = "https://testgraphacct.gremlin.cosmosdb.azure.com:443/"; 
config.primaryKey = "Pams6e7LEUS7LJ2Qk0fjZf3eGo65JdMWHmyn65i52w8ozPX2oxY3iP0yu05t9v1WymAHNcMwPIqNAEv3XDFsEg==";
config.database = "graphdb"
config.collection = "Persons"

module.exports = config;

Execute o aplicativo de consoleRun the console app

  1. Abra uma janela de terminal e mude (por meio do comando cd) para um diretório de instalação para o arquivo package.json incluído no projeto.Open a terminal window and change (via cd command) to the installation directory for the package.json file that's included in the project.

  2. Executar npm install para instalar os módulos npm necessários, incluindo gremlin.Run npm install to install the required npm modules, including gremlin.

  3. Execute node app.js em um terminal para iniciar o aplicativo de nó.Run node app.js in a terminal to start your node application.

Procurar com o Data ExplorerBrowse with Data Explorer

Agora você pode voltar ao Data Explorer no Portal do Azure e exibir, consultar, modificar e trabalhar com seus novos dados dos grafos.You can now go back to Data Explorer in the Azure portal to view, query, modify, and work with your new graph data.

No Data Explorer, o novo banco de dados aparece no painel Grafos.In Data Explorer, the new database appears in the Graphs pane. Expanda o banco de dados, seguido pelo contêiner e, em seguida, selecione Grafo.Expand the database, followed by the container, and then select Graph.

Os dados gerados pelo aplicativo de exemplo são exibidos no próximo painel dentro da guia Grafo quando você seleciona Aplicar filtro.The data generated by the sample app is displayed in the next pane within the Graph tab when you select Apply Filter.

Tente preencher g.V() com .has('firstName', 'Thomas') para testar o filtro.Try completing g.V() with .has('firstName', 'Thomas') to test the filter. Observe que o valor diferencia maiúsculas de minúsculas.Note that the value is case sensitive.

Examinar SLAs no Portal do AzureReview SLAs in the Azure portal

O portal do Azure monitora a taxa de transferência, armazenamento, disponibilidade, latência e consistência da conta do Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Gráficos de métricas associados a um SLA (Contrato de Nível de Serviço) do Azure Cosmos DB mostram o valor do SLA em comparação com o desempenho real.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Esse conjunto de métricas torna o monitoramento dos SLAs transparente.This suite of metrics makes monitoring your SLAs transparent.

Para examinar as métricas e os SLAs:To review metrics and SLAs:

  1. Selecione Métricas no menu de navegação da sua conta do Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Selecione uma guia, tal como Latência, e selecione um período à direita.Select a tab such as Latency, and select a timeframe on the right. Comparar as linhas Real e SLA dos gráficos.Compare the Actual and SLA lines on the charts.

    Pacote de métricas do Azure Cosmos DB

  3. Examine as métricas nas outras guias.Review the metrics on the other tabs.

Limpar seus recursosClean up your resources

Quando você concluir seu aplicativo Web e a conta do Azure Cosmos DB, poderá excluir os recursos do Azure criados para não incorrer em mais cobranças.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Para excluir os recursos:To delete the resources:

  1. No portal do Azure, selecione Grupos de recursos no canto esquerdo.In the Azure portal, select Resource groups on the far left. Se o menu esquerdo estiver recolhido, selecione Expandir botão para expandi-lo.If the left menu is collapsed, select Expand button to expand it.

  2. Selecione o grupo de recursos que você criou para este início rápido.Select the resource group you created for this quickstart.

    Métricas no portal do Azure

  3. Na nova janela, selecione Excluir grupo de recursos.In the new window, select Delete resource group.

    Métricas no portal do Azure

  4. Na próxima janela, insira o nome do grupo de recursos a ser excluído e selecione Excluir.In the next window, enter the name of the resource group to delete, and then select Delete.

Próximas etapasNext steps

Neste artigo, você aprendeu como criar uma conta do Azure Cosmos DB, como criar um grafo usando o Data Explorer e como executar um aplicativo.In this article, you learned how to create an Azure Cosmos DB account, create a graph by using Data Explorer, and run an app. Agora, você pode criar consultas mais complexas e implementar uma lógica de passagem de grafo avançada usando o Gremlin.You can now build more complex queries and implement powerful graph traversal logic by using Gremlin.