Esta página foi traduzida pela API Cloud Translation.

Configurar índices com a API REST

Esta página descreve como criar, eliminar e listar índices compostos do modo Datastore através da API REST do modo Datastore.

A CLI do Google Cloud oferece uma forma conveniente de aceder à API REST do modo Datastore e gerir os seus índices compostos. No entanto, pode aceder diretamente à API REST do modo Datastore para criar as suas próprias ferramentas de gestão dos seus índices compostos. Por exemplo, pode criar ferramentas para automatizar o aprovisionamento e a gestão de índices.

Autenticação e autorização

Para aceder aos métodos da API REST do Firestore no modo Datastore abaixo, tem de autenticar o seu pedido fornecendo um token de acesso do Google OAuth 2.0 com um dos seguintes âmbitos:

https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform

Os exemplos de cURL e PowerShell abaixo usam o comando gcloud auth print-access-token para autenticar pedidos. Para mais informações sobre como obter uma chave de acesso, consulte o artigo Utilizar o OAuth 2.0 para aceder às APIs Google.

Autorização

O utilizador, o grupo ou a conta de serviço autenticados no pedido têm de ter autorização para aceder aos métodos da API. Para autorizar o acesso aos métodos de indexação, atribua uma das seguintes funções de gestão de identidade e de acesso (IAM):

Para ter acesso total de leitura e edição ao índice, conceda uma destas funções:
- roles/owner
- roles/editor
- roles/datastore.owner
- roles/datastore.indexAdmin
Para acesso de leitura do índice apenas (obter e listar), conceda uma destas funções:
- roles/viewer
- roles/datastore.user
- roles/datastore.viewer

Para mais informações sobre a atribuição destas funções, consulte o artigo sobre como conceder, alterar e revogar o acesso a recursos.

Antes de começar

Os exemplos de curl e PowerShell abaixo usam a CLI do Google Cloud (CLI do Google Cloud) para autenticar pedidos. Para executar estes exemplos localmente, instale e inicialize a CLI Google Cloud.

Em alternativa, pode aceder ao gcloud e ao curl a partir da Google Cloud consola através do Cloud Shell.

Inicie o Cloud Shell

Criar um índice composto

Para criar um novo índice composto, use o método projects.indexes.create.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

project-id: o ID do seu projeto
kind: o tipo de entidade a indexar
include-ancestors: se deve ou não incluir antecessores de entidades no índice para suportar consultas de antecessores, NONE ou ALL_ANCESTORS
property-name: a propriedade a indexar. Tem de especificar duas ou mais propriedades
index-direction: a ordem de ordenação de cada propriedade, ASCENDING ou DESCENDING

Método HTTP e URL:

POST https://datastore.googleapis.com/v1/projects/project-id/indexes

Corpo JSON do pedido:

{
  "kind": "kind",
  "ancestor": "include-ancestors",
  "properties": [
      {
          "name": "property-name",
          "direction": "index-direction"
      },
      {
          "name": "property-name",
          "direction": "index-direction"
      }
  ]
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes"

PowerShell

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes" | Select-Object -Expand Content

Explorador de APIs

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Deve receber uma resposta JSON semelhante à seguinte:

{
  "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIDgxZGVhZDM0ZDc4MS1jMjJhLWQ1ZTQtYmMyNS1iYjY2NWVlZCQadGx1YWZlZAcSMXJoLXJleGVkbmktbmltZGERClIS",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
    "common": {
      "startTime": "2019-12-05T22:27:19.238Z",
      "operationType": "CREATE_INDEX",
      "state": "INITIALIZING"
    },
    "indexId": "CICAgJiUpoMK"
  }
}

A receber o estado do índice

O modo Datastore atribui a cada índice um ID de índice exclusivo. Pode usar este ID do índice para obter o estado de um único índice com o método projects.indexes.get:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

project-id: o ID do seu projeto
index-id: um ID de índice composto

Método HTTP e URL:

GET https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id

Para enviar o seu pedido, escolha uma destas opções:

curl

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id"

PowerShell

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id" | Select-Object -Expand Content

Explorador de APIs

Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Preencha todos os campos obrigatórios e clique em Executar.

Deve receber uma resposta JSON semelhante à seguinte:

{
  "projectId": "project-id",
  "indexId": "index-id",
  "kind": "Task",
  "ancestor": "NONE",
  "properties": [
    {
      "name": "done",
      "direction": "ASCENDING"
    },
    {
      "name": "priority",
      "direction": "ASCENDING"
    }
  ],
  "state": "READY"
}

Estado do índice

Veja o estado do índice para obter informações sobre o progresso e mensagens de erro. Não pode usar um índice para consultas até que este atinja o estado READY. Os estados possíveis do índice incluem:

CREATING: criação do índice em curso.
ALREADY_EXISTS: não é possível concluir a operação porque este índice já existe.
ERROR: falha na criação do índice. Corrija os dados que causaram o erro, elimine este índice e, em seguida, crie o índice novamente.
READY: criação do índice concluída. O índice está pronto a ser usado para consultas.

Eliminar um índice composto

Método HTTP e URL:

DELETE https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id

Para enviar o seu pedido, escolha uma destas opções:

curl

Execute o seguinte comando:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id"

PowerShell

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id" | Select-Object -Expand Content

Explorador de APIs

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Apresentar todos os índices compostos

Para listar todos os índices compostos de uma base de dados do modo Datastore, use o método projects.indexes.list.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

project-id: o ID do seu projeto

Método HTTP e URL:

GET https://datastore.googleapis.com/v1/projects/project-id/indexes

Para enviar o seu pedido, escolha uma destas opções:

curl

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes"

PowerShell

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes" | Select-Object -Expand Content

Explorador de APIs

Deve receber uma resposta JSON semelhante à seguinte:

{
 "indexes": [
  {
   "projectId": "project-id",
   "indexId": "CICAgOjXh4EK",
   "kind": "Task",
   "ancestor": "NONE",
   "properties": [
    {
     "name": "done",
     "direction": "ASCENDING"
    },
    {
     "name": "priority",
     "direction": "ASCENDING"
    }
   ],
   "state": "READY"
  },
  {
   "projectId": "project-id",
   "indexId": "CICAgNiroIEK",
   "kind": "Task",
   "ancestor": "NONE",
   "properties": [
    {
     "name": "due-date",
     "direction": "DESCENDING"
    },
    {
     "name": "priority",
     "direction": "ASCENDING"
    }
   ],
   "state": "CREATING"
  }
 ]
}

Configurar índices com a API REST Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Autenticação e autorização

Autorização

Antes de começar

Criar um índice composto

curl

PowerShell

Explorador de APIs

A receber o estado do índice

curl

PowerShell

Explorador de APIs

Estado do índice

Eliminar um índice composto

curl

PowerShell

Explorador de APIs

Apresentar todos os índices compostos

curl

PowerShell

Explorador de APIs

Configurar índices com a API REST