Partilhar via

Guia de início rápido: usar o construtor de API de dados com o NoSQL

Neste quickstart, cria endpoints GraphQL para um emulador local Azure Cosmos DB for NoSQL usando o Data API builder (DAB).

Observação

O Azure Cosmos DB para NoSQL no criador de APIs de dados suporta apenas endpoints GraphQL. Endpoints REST não estão disponíveis para este tipo de base de dados.

Pré-requisitos

Instalar a CLI do construtor de API de dados

Instala o pacote Microsoft.DataApiBuilder do NuGet como ferramenta .NET.

  1. Use dotnet tool install para instalar a versão mais recente do Microsoft.DataApiBuilder com o --global argumento.

    dotnet tool install --global Microsoft.DataApiBuilder

    Observação

    Se o pacote já estiver instalado, atualize-o usando dotnet tool update.

    dotnet tool update --global Microsoft.DataApiBuilder

  2. Verifique se a ferramenta está instalada com dotnet tool list utilizando o argumento --global.

    dotnet tool list --global

Puxa a imagem do emulador

Descarregue a imagem do emulador Azure Cosmos DB para NoSQL. Este download pode demorar alguns minutos porque a imagem do emulador é grande.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Iniciar o emulador

Executa o emulador da base de dados Cosmos no Docker. A AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE definição é necessária para que o emulador anuncie 127.0.0.1 os seus endpoints de rede, tornando-os acessíveis a partir da sua máquina anfitriã.

docker run --name dab-cosmos --publish 8081:8081 --publish 10250-10255:10250-10255 --env AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 --detach mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Observação

O emulador inicia 11 partições internas e pode demorar entre 30 a 60 segundos a ficar pronto. Podes verificar se está a correr abrindo https://localhost:8081/_explorer/index.html no teu navegador. O seu navegador pode alertar sobre o certificado auto-assinado—é seguro avançar.

Instalar o certificado do emulador

O emulador Cosmos DB utiliza um certificado SSL auto-assinado. Descarregue e confie neste certificado para que o Data API Builder possa ligar-se ao emulador.

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
sudo cp ~/emulatorcert.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Criar a base de dados e os dados de inicialização

Use o Data Explorer integrado no emulador para criar uma base de dados, um contentor e itens de exemplo. Não são necessárias ferramentas adicionais — o Explorador de Dados corre no seu navegador como parte do emulador.

  1. Abra o Explorador de Dados em https://localhost:8081/_explorer/index.html.

  2. Selecionar Nova Base de Dados. Insira todos como o ID da base de dados e selecione OK.

  3. Expande a base de dados de tarefas , seleciona o menu de reticências (...) e escolhe Novo Contentor. Introduz todos como o ID do contentor e /id como chave de partição, depois selecione OK.

  4. Expande a caixa todos e seleciona Itens. Depois seleciona Novo Item, substitui o JSON predefinido pelo seguinte conteúdo e seleciona Guardar. Repete para cada item.

    Ponto 1:

    {
  "id": "1",
  "title": "Walk the dog",
  "completed": false
}

    Item 2:

    {
  "id": "2",
  "title": "Feed the fish",
  "completed": false
}

    Item 3:

    {
  "id": "3",
  "title": "Comb the cat",
  "completed": true
}

Criar um ficheiro de esquema GraphQL

O Azure Cosmos DB para NoSQL requer um ficheiro de esquema GraphQL. Crie um arquivo nomeado schema.gql com o seguinte conteúdo.

type Todo @model {
  id: ID!
  title: String!
  completed: Boolean!
}

Configurar construtor de APIs de Dados

  1. Inicialize a configuração com a cadeia de ligação padrão do emulador.

    dab init --database-type "cosmosdb_nosql" --host-mode "Development" --cosmosdb_nosql-database todos --graphql-schema schema.gql --connection-string "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="

  2. Adiciona a entidade Todo .

    dab add Todo --source "todos" --permissions "anonymous:*"

O seu dab-config.json ficheiro deverá agora parecer semelhante ao seguinte exemplo:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "connection-string": "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
    "options": {
      "database": "todos",
      "schema": "schema.gql"
    }
  },
  "runtime": {
    "graphql": {
      "enabled": true
    },
    "host": {
      "mode": "development"
    }
  },
  "entities": {
    "Todo": {
      "source": {
        "object": "todos",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            "*"
          ]
        }
      ]
    }
  }
}

Sugestão

Pode ignorar os comandos dab init e dab add e criar os ficheiros dab-config.json e schema.gql diretamente com o conteúdo mostrado aqui.

Inicie a API

Use dab start para executar a ferramenta e criar endpoints de API para a sua entidade.

dab start

A saída deve incluir o endereço da API em execução.

      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>

Sugestão

Neste exemplo, o aplicativo está sendo executado na localhost porta 5000. Seu aplicativo em execução pode ter um endereço e uma porta diferentes.

Testar a API

  1. Abra o seu navegador e navegue até ao endpoint GraphQL.

    http://localhost:5000/graphql

    Em modo Desenvolvimento, este URL abre o IDE do Nitro GraphQL.

  2. Crie um novo documento e execute a seguinte consulta para recuperar todos os itens pendentes.

    query {
  todos {
    items {
      id
      title
      completed
    }
  }
}

  3. A resposta deve incluir os três itens da lista de tarefas.

    {
  "data": {
    "todos": {
      "items": [
        { "id": "1", "title": "Walk the dog", "completed": false },
        { "id": "2", "title": "Feed the fish", "completed": false },
        { "id": "3", "title": "Comb the cat", "completed": true }
      ]
    }
  }
}

Limpeza

Pare e remova o contentor Docker quando terminar.

docker stop dab-cosmos && docker rm dab-cosmos

Próximo passo

Pontos finais do GraphQL

Conteúdo relacionado

  • Last updated on