Quickstart: Criar uma base de dados de gráficos em Azure Cosmos DB usando PHP e o portal Azure

APLICA-SE A: Gremlin API

Este início rápido mostra como utilizar o PHP e a Gremlin API do Azure Cosmos DB para criar uma aplicação de consola através da clonagem de um exemplo do GitHub. Este guia de introdução também o acompanha ao longo da criação de uma conta do Azure Cosmos DB ao utilizar o portal do Azure baseado na Web.

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 tabela, 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.

Pré-requisitos

Se não tiver uma subscrição do Azure,crie uma conta gratuita antes de começar. Em alternativa, pode experimentar gratuitamente a Azure Cosmos DB sem uma subscrição Azure, gratuitamente e compromissos.

Além disso:

Criar uma conta de base de dados

Antes de poder criar uma base de dados de gráficos, tem de criar uma conta de base de dados do Gremlin (Gráfico) com o Azure Cosmos DB.

  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 trabalhar com código. Vamos clonar uma aplicação 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 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-php-getting-started.git
    

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. Os fragmentos são obtidos a partir do ficheiro connect.php na pasta C:\git-samples\azure-cosmos-db-graph-php-getting-started. Caso contrário, pode avançar diretamente para Update your connection string (Atualizar a cadeia de ligação).

  • O Gremlin connection é inicializado no início do ficheiro connect.php que utiliza o objeto $db.

    $db = new Connection([
        'host' => '<your_server_address>.graphs.azure.com',
        'username' => '/dbs/<db>/colls/<coll>',
        'password' => 'your_primary_key'
        ,'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  • São executados uma série de passos do Gremlin com o método $db->send($query);.

    $query = "g.V().drop()";
    ...
    $result = $db->send($query);
    $errors = array_filter($result);
    }
    

Atualizar as informações da ligação

Agora, regresse ao portal do Azure para obter as informações da ligação e copie-as para a aplicação. Estas definições permitem à aplicação comunicar com a base de dados alojada.

  1. No portal do Azure, clique em Chaves.

    Copie a primeira parte do valor do URI.

    Ver e copiar uma chave de acesso no portal do Azure, página Chaves

  2. Abra o ficheiro connect.php e, na linha 8, cole o valor do URI sobre your_server_address.

    A inicialização do objeto de ligação deve agora ter um aspeto semelhante ao código seguinte:

    $db = new Connection([
        'host' => 'testgraphacct.gremlin.cosmosdb.azure.com',
        'username' => '/dbs/<db>/colls/<coll>',
        'password' => 'your_primary_key'
        ,'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  3. Altere o parâmetro username no objeto da ligação com o nome da base de dados e do gráfico. Se utilizou os valores recomendados do sample-database e sample-graph, deve ser semelhante ao seguinte código:

    'username' => '/dbs/sample-database/colls/sample-graph'

    Neste momento, todo o objeto de ligação deve ser semelhante ao seguinte fragmento de código:

    $db = new Connection([
        'host' => 'testgraphacct.gremlin.cosmosdb.azure.com',
        'username' => '/dbs/sample-database/colls/sample-graph',
        'password' => 'your_primary_key',
        'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  4. No portal do Azure, utilize o botão de cópia para copiar a CHAVE PRIMÁRIA e cole-a sobre your_primary_key no parâmetro palavra-passe.

    A inicialização do objeto de Ligação deve agora ter um aspeto semelhante ao código seguinte:

    $db = new Connection([
        'host' => 'testgraphacct.graphs.azure.com',
        'username' => '/dbs/sample-database/colls/sample-graph',
        'password' => '2Ggkr662ifxz2Mg==',
        'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  5. Guarde o ficheiro connect.php.

Executar a aplicação de consola

  1. Na janela de terminal do git, cd na pasta azure-cosmos-db-graph-php-getting-started.

    cd "C:\git-samples\azure-cosmos-db-graph-php-getting-started"
    
  2. Na janela de terminal do git, utilize o seguinte comando para instalar as dependências de PHP necessárias.

    composer install
    
  3. Na janela de terminal do git, utilize o seguinte comando para iniciar a aplicação de PHP.

    php connect.php
    

    A janela de terminal apresenta os vértices a adicionar ao gráfico.

    Se ocorrerem erros de tempo limite, verifique se atualizou as informações de ligação corretamente em Atualizar as suas informações de ligação e tente executar o último comando novamente.

    Assim que o programa parar, prima Enter e, em seguida, mude novamente para o portal do Azure no browser.

Rever e adicionar dados de exemplo

Agora, pode voltar ao Data Explorer e ver os vértices adicionados ao gráfico e adicionar mais pontos de dados.

  1. Clique em Data Explorer, expanda sample-graph, clique em Gráfico e clique em Aplicar Filtro.

    A screenshot mostra Graph selecionados a partir do A P I com a opção de Aplicar Filtro.

  2. Na lista Resultados, repare nos utilizadores novos que são adicionados ao gráfico. Selecione Ben e note que estão ligados ao Robin. Pode mover os vértices ao redor ao arrastar e largar, ampliar e reduzir ao deslocar a roda do rato e expandir o tamanho do gráfico com a seta dupla.

    Vértices novos no gráfico no Data Explorer no portal do Azure

  3. Vamos adicionar alguns utilizadores novos. Clique no botão Vértice Novo para adicionar os dados ao gráfico.

    A screenshot mostra o painel New Vertex onde pode introduzir valores.

  4. Introduza uma etiqueta de pessoa.

  5. Clique em Adicionar propriedade para adicionar cada uma das seguintes propriedades. Tenha em atenção que pode criar propriedades exclusivas para cada pessoa no seu gráfico. Só é necessária a chave de identificação.

    Chave Valor Notas
    id ashley O identificador exclusivo do vértice. Se não especificar, é gerado um id automaticamente.
    Género feminino
    técnico java

    Nota

    Neste guia de introdução, criará uma coleção não particionada. No entanto, se criar uma coleção particionada mediante a especificação de uma chave de partição durante a criação da coleção, terá de incluir a chave da partição como uma chave em cada vértice novo.

  6. Clique em OK. Poderá ter de expandir o ecrã para ver OK, na parte inferior.

  7. Clique em Vértice Novo novamente e adicione outro utilizador.

  8. Introduza uma etiqueta de pessoa.

  9. Clique em Adicionar propriedade para adicionar cada uma das seguintes propriedades:

    Chave Valor Notas
    id rakesh O identificador exclusivo do vértice. Se não especificar, é gerado um id automaticamente.
    Género masculino
    escola MIT
  10. Clique em OK.

  11. Clique no botão Aplicar Filtro com o filtro g.V() predefinido para apresentar todos os valores no gráfico. Todos os utilizadores aparecem agora na lista Resultados.

    À medida que adiciona mais dados, pode utilizar filtros para limitar os resultados. Por predefinição, o Data Explorer utiliza o g.V() para obter todos os vértices num gráfico. Pode alterá-lo para uma consulta de gráfico diferente, como g.V().count(), para devolver uma contagem de todos os vértices no gráfico no formato JSON. Se tiver alterado o filtro, altere o filtro de volta para g.V() e clique em Aplicar Filtro para apresentar todos os resultados novamente.

  12. Agora, pode ligar rakesh e ashley. Confirme que ashley está selecionada na lista Resultados e clique no botão Editar junto a Destinos, no canto inferior direito. Poderá ter de alargar a janela para ver a área Propriedades.

    Alterar o destino de um vértice de um gráfico

  13. Na caixa Destino, escreva rakesh, na caixa Etiqueta da extremidade, escreva Conhece e clique no visto.

    Adicionar uma ligação entre ashley e rakesh no Data Explorer

  14. Agora, selecione rakesh na lista de resultados e veja se ashley e rakesh estão ligados.

    Dois vértices ligados no Data Explorer

    Esta ação conclui a parte da criação de recursos deste início rápido. Pode continuar a adicionar vértices ao seu gráfico, modificar os vértices existentes ou alterar as consultas. Agora vamos rever as métricas que o Azure Cosmos DB oferece e, em seguida, limpar os recursos.

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)