Início Rápido: Criar um banco de dados de grafo no Azure Cosmos DB usando o Python e o portal do AzureQuickstart: Create a graph database in Azure Cosmos DB using Python and the Azure portal

Este início rápido mostra como usar o PHP e a API do Python do Azure Cosmos DB para criar um aplicativo de console clonando um exemplo do GitHub.This quickstart shows how to use Python and the Azure Cosmos DB Gremlin API to build a console app by cloning an example from GitHub. Este guia de início rápido também mostra as etapas para a criação de uma conta do Azure Cosmos DB usando o Portal do Azure baseado na Web.This quickstart also walks you through the creation of an Azure Cosmos DB account by using the web-based Azure portal.

O Azure Cosmos DB é o serviço de banco de dados multimodelo distribuído globalmente da Microsoft.Azure Cosmos DB is Microsoft's globally distributed multi-model database service. É possível criar e consultar rapidamente documentos, tabelas, valores-chave e bancos de dados de gráfico, todos os quais se beneficiam de recursos de distribuição global e escala horizontal e no núcleo do Azure Cosmos DB.You can quickly create and query document, table, key-value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Observação

Este início rápido exige uma conta de banco de dados de grafo criada depois de 20 de dezembro de 2017.This quickstart requires a graph database account created after December 20th, 2017. As contas existentes oferecerão suporte a Python depois de serem migradas para a disponibilidade geral.Existing accounts will support Python once they’re migrated to general availability.

Pré-requisitosPrerequisites

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. Como alternativa, você pode Experimentar o Azure Cosmos DB gratuitamente sem uma assinatura do Azure, sem ônus e sem compromisso.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. Alternatively, you can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments.

Além disso:In addition:

Criar uma conta de banco de dadosCreate a database account

Antes de criar um banco de dados de grafo, você precisa criar uma conta do banco de dados Gremlin (Graph) com o Azure Cosmos DB.Before you can create a graph database, you need to create a Gremlin (Graph) database account with Azure Cosmos DB.

  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. Selecione Data Explorer > Novo Grafo.Select 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. Depois que o formulário for preenchido, selecione OK.Once the form is filled out, select OK.

Clonar o aplicativo de exemploClone the sample application

Agora, vamos trabalhar com o código.Now let's switch to working with code. Vamos clonar um aplicativo de API do Gremlin do GitHub, definir a cadeia de conexão e executá-lo.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 uma pasta para instalar o aplicativo de exemplo.Open a git terminal window, such as git bash, and use the cd command to change to a 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-python-getting-started.git
    

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. Os snippets de códigos são todos obtidos a partir do arquivo connect.py na pasta C:\git-samples\azure-cosmos-db-graph-python-getting-started.The snippets are all taken from the connect.py file in the C:\git-samples\azure-cosmos-db-graph-python-getting-started\ folder. Caso contrário, você poderá pular para Atualizar sua cadeia de conexão.Otherwise, you can skip ahead to Update your connection string.

  • O Gremlin client é inicializado na linha 104 em connect.py:The Gremlin client is initialized in line 104 in connect.py:

    ...
    client = client.Client('wss://<YOUR_ENDPOINT>.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    ...
    
  • Uma série de etapas de Gremlin são declaradas no início do arquivo connect.py.A series of Gremlin steps are declared at the beginning of the connect.py file. Elas são executadas usando o método client.submitAsync():They are then executed using the client.submitAsync() method:

    client.submitAsync(_gremlin_cleanup_graph)
    

Atualizar as informações de conexãoUpdate your connection information

Agora, volte ao Portal do Azure para obter as informações de conexão e copiá-las para o aplicativo.Now go back to the Azure portal to get your connection information and copy it into the app. Essas configurações permitem que seu aplicativo se comunique com o banco de dados hospedado.These settings enable your app to communicate with your hosted database.

  1. No Portal do Azure, clique em Chaves.In the Azure portal, click Keys.

    Copie a primeira parte do valor do URI.Copy the first portion of the URI value.

    Exibir e copiar uma chave de acesso no Portal do Azure, página Chaves

  2. Abra o arquivo connect.py e, na linha 104, cole o valor URI <YOUR_ENDPOINT> aqui:Open the connect.py file and in line 104 paste the URI value over <YOUR_ENDPOINT> in here:

    client = client.Client('wss://<YOUR_ENDPOINT>.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    

    Agora, a parte do URI do objeto do cliente deve ser semelhante a este código:The URI portion of the client object should now look similar to this code:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    
  3. Altere o segundo parâmetro do objeto client para substituir a cadeia de caracteres <YOUR_DATABASE> e <YOUR_COLLECTION_OR_GRAPH>.Change the second parameter of the client object to replace the <YOUR_DATABASE> and <YOUR_COLLECTION_OR_GRAPH> strings. Se você tiver usado os valores sugeridos, o parâmetro deve se parecer com este código:If you used the suggested values, the parameter should look like this code:

    username="/dbs/sample-database/colls/sample-graph"

    Agora, todo o objeto client deve se parecer com este código:The entire client object should now look like this code:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/sample-database/colls/sample-graph", 
        password="<YOUR_PASSWORD>")
    
  4. No Portal do Azure, use o botão copiar para copiar a CHAVE PRIMÁRIA e colá-la em <YOUR_PASSWORD> no parâmetro password=<YOUR_PASSWORD>.In the Azure portal, use the copy button to copy the PRIMARY KEY and paste it over <YOUR_PASSWORD> in the password=<YOUR_PASSWORD> parameter.

    Agora, toda a definição do objeto client deve se parecer com este código:The entire client object definition should now look like this code:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/sample-database/colls/sample-graph", 
        password="asdb13Fadsf14FASc22Ggkr662ifxz2Mg==")
    
  5. Salve o arquivo connect.py.Save the connect.py file.

Execute o aplicativo de consoleRun the console app

  1. Na janela do terminal git, cd para a pasta azure-cosmos-db-graph-python-getting-started.In the git terminal window, cd to the azure-cosmos-db-graph-python-getting-started folder.

    cd "C:\git-samples\azure-cosmos-db-graph-python-getting-started"
    
  2. Na janela do terminal git, use o seguinte comando para instalar os pacotes necessários do Python.In the git terminal window, use the following command to install the required Python packages.

    pip install -r requirements.txt
    
  3. Na janela do terminal git, use os comandos a seguir para iniciar o aplicativo Python.In the git terminal window, use the following command to start the Python application.

    python connect.py
    

    A janela do terminal exibe os vértices e margens sendo adicionados ao grafo.The terminal window displays the vertices and edges being added to the graph.

    Se ocorrerem erros de tempo limite, verifique se você atualizou as informações de conexão corretamente em Atualizar suas informações de conexão e também tente executar o último comando novamente.If you experience timeout errors, check that you updated the connection information correctly in Update your connection information, and also try running the last command again.

    Após o programa parar, pressione Enter e volte para o Portal do Azure no seu navegador da Internet.Once the program stops, press Enter, then switch back to the Azure portal in your internet browser.

Revisar e adicionar dados de exemploReview and add sample data

Após a inserção dos vértices e das bordas, você pode voltar para o Data Explorer, ver os vértices adicionados ao grafo e acrescentar pontos de dados adicionais.After the vertices and edges are inserted, you can now go back to Data Explorer and see the vertices added to the graph, and add additional data points.

  1. Clique em Data Explorer, expanda grafo de exemplo, clique em Grafo e em Aplicar Filtro.Click Data Explorer, expand sample-graph, click Graph, and then click Apply Filter.

    Criar novos documentos no Data Explorer no portal do Azure

  2. Na lista Resultados, observe que três novos usuários são adicionados ao grafo.In the Results list, notice three new users are added to the graph. Você pode mover os vértices arrastando e soltando, ampliar e reduzir rolando o botão de rolagem do mouse e expandir o tamanho do grafo com a seta dupla.You can move the vertices around by dragging and dropping, zoom in and out by scrolling the wheel of your mouse, and expand the size of the graph with the double-arrow.

    Novos vértices no grafo no Data Explorer no portal do Azure

  3. Vamos adicionar alguns novos usuários.Let's add a few new users. Clique no botão Novo Vértice para adicionar dados ao grafo.Click the New Vertex button to add data to your graph.

    Criar novos documentos no Data Explorer no portal do Azure

  4. Digite um rótulo de pessoa.Enter a label of person.

  5. Clique em Adicionar propriedade para adicionar cada uma das propriedades a seguir.Click Add property to add each of the following properties. Observe que você pode criar propriedades exclusivas para cada pessoa no grafo.Notice that you can create unique properties for each person in your graph. Somente a chave da id é necessária.Only the id key is required.

    chavekey valuevalue ObservaçõesNotes
    pkpk /pk/pk
    IDid ashleyashley O identificador exclusivo do vértice.The unique identifier for the vertex. Se você não especificar uma ID, ela será gerada para você.If you don't specify an id, one is generated for you.
    gendergender femininofemale
    técnicotech javajava

    Observação

    Neste início rápido, criamos uma coleção não particionada.In this quickstart create a non-partitioned collection. No entanto, se você criar uma coleção particionada especificando uma chave de partição durante a criação da coleção, então, precisará incluir a chave de partição como uma chave em cada novo vértice.However, if you create a partitioned collection by specifying a partition key during the collection creation, then you need to include the partition key as a key in each new vertex.

  6. Clique em OK.Click OK. Talvez seja necessário expandir a tela para ver OK na parte inferior da tela.You may need to expand your screen to see OK on the bottom of the screen.

  7. Clique em Novo Vértice novamente e acrescente um novo usuário.Click New Vertex again and add an additional new user.

  8. Digite um rótulo de pessoa.Enter a label of person.

  9. Clique em Adicionar propriedade para adicionar cada uma das propriedades a seguir:Click Add property to add each of the following properties:

    chavekey valuevalue ObservaçõesNotes
    pkpk /pk/pk
    IDid rakeshrakesh O identificador exclusivo do vértice.The unique identifier for the vertex. Se você não especificar uma ID, ela será gerada para você.If you don't specify an id, one is generated for you.
    gendergender masculinomale
    escolaschool MITMIT
  10. Clique em OK.Click OK.

  11. Clique no botão Aplicar Filtro com o filtro g.V() padrão para exibir todos os valores no gráfico.Click the Apply Filter button with the default g.V() filter to display all the values in the graph. Todos os usuários agora aparecem na lista Resultados.All of the users now show in the Results list.

    Conforme você adiciona mais dados, pode usar os filtros para limitar os resultados.As you add more data, you can use filters to limit your results. Por padrão, o Data Explorer usa g.V() para recuperar todos os vértices em um grafo.By default, Data Explorer uses g.V() to retrieve all vertices in a graph. Você pode alterá-lo para outra consulta de grafo, como g.V().count(), para retornar uma contagem de todos os vértices no grafo no formato JSON.You can change it to a different graph query, such as g.V().count(), to return a count of all the vertices in the graph in JSON format. Se você tiver alterado o filtro, altere o filtro de volta para g.V() e clique em Aplicar Filtro para exibir todos os resultados novamente.If you changed the filter, change the filter back to g.V() and click Apply Filter to display all the results again.

  12. Agora, podemos conectar rakesh e ashley.Now we can connect rakesh and ashley. Verifique se ashley está selecionada na lista Resultados, em seguida, clique no botão de edição ao lado de Destinos à direita inferior.Ensure ashley is selected in the Results list, then click the edit button next to Targets on lower right side. Talvez seja necessário ampliar a janela para ver a área Propriedades.You may need to widen your window to see the Properties area.

    Alterar o destino de um vértice em um grafo

  13. Na caixa Destino, digite rakesh e na caixa Rótulo da aresta, digite conhece, em seguida, clique na marca de seleção.In the Target box type rakesh, and in the Edge label box type knows, and then click the check.

    Adicionar uma conexão entre ashley e rakesh no Data Explorer

  14. Agora, selecione rakesh na lista de resultados e veja se ashley e rakesh estão conectados.Now select rakesh from the results list and see that ashley and rakesh are connected.

    Dois vértices conectados no Data Explorer

    Isso conclui a parte da criação de recursos deste tutorial.That completes the resource creation part of this tutorial. Você pode continuar a adicionar vértices ao seu grafo, modificar os vértices existentes ou alterar as consultas.You can continue to add vertexes to your graph, modify the existing vertexes, or change the queries. Agora vamos examinar as métricas que o Azure Cosmos DB fornece e, em seguida, limpar os recursos.Now let's review the metrics Azure Cosmos DB provides, and then clean up the resources.

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 recursosClean up 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 início rápido, 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 quickstart, you've learned how to create an Azure Cosmos DB account, create a graph using the 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 using Gremlin.