Esta página foi traduzida pela API Cloud Translation.

Como configurar índices com a API REST

Esta página descreve como criar, excluir e listar índices compostos no modo Datastore usando a API REST do modo Datastore.

A CLI do Google Cloud oferece uma maneira conveniente de acessar a API REST no modo Datastore e gerenciar seus índices compostos. No entanto, é possível acessar diretamente a API REST do modo Datastore para criar suas próprias ferramentas de gerenciamento de índices compostos. Por exemplo, é possível criar ferramentas para automatizar o provisionamento e gerenciamento de índices.

Autenticação e autorização

Para acessar o Firestone nos métodos da API REST no modo Datastore a seguir, autentique sua solicitação fornecendo um token de acesso Google OAuth 2.0 com um dos seguintes escopos:

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 solicitações. Para mais informações sobre como ter um token de acesso, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Autorização

O usuário, grupo ou conta de serviço autenticado na solicitação precisa ter autorização para acessar os métodos da API. Para autorizar o acesso aos métodos de indexação, atribua um dos seguintes papéis de gerenciamento de identidade e acesso (IAM, na sigla em inglês):

Para ter acesso completo de leitura e edição do índice, conceda um destes papéis:
- roles/owner
- roles/editor
- roles/datastore.owner
- roles/datastore.indexAdmin
Somente para acesso de leitura de índice (get e list), conceda um destes papéis:
- roles/viewer
- roles/datastore.user
- roles/datastore.viewer

Para obter mais informações sobre como atribuir esses papéis, consulte conceder, alterar e revogar acesso a recursos.

Antes de começar

Os exemplos de curl e PowerShell abaixo usam a Google Cloud CLI (Google Cloud CLI) para autenticar solicitações. Para executar esses exemplos localmente, instale e inicialize a Google Cloud CLI.

Como alternativa, é possível acessar gcloud e curl no console do Google Cloud usando o Cloud Shell.

Iniciar Cloud Shell

Como criar um índice composto

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

project-id: ID do projeto
kind: tipo de entidade que será indexada
include-ancestors: inclusão ou não de ancestrais de entidade no índice para aceitar consultas de ancestrais, NONE ou ALL_ANCESTORS
property-name: propriedade que será indexada, é preciso especificar duas ou mais propriedades
index-direction: ordem de classificação de cada propriedade, ASCENDING ou DESCENDING

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

APIs Explorer

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
  }
}

Como ter o status do índice

O modo Datastore fornece a cada índice um ID de índice exclusivo. Use esse ID de índice para receber o status de um único índice com o método project.indexes.get:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

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

Método HTTP e URL:

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

Para enviar a solicitação, 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

APIs Explorer

Abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

Você receberá uma resposta JSON semelhante a esta:

{
  "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 das informações de andamento e das mensagens de erro. Não é possível usar um índice para consultas até que ele atinja o estado READY. Veja os possíveis estados de índice:

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

Como excluir um índice composto

Método HTTP e URL:

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

Para enviar a solicitação, 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

APIs Explorer

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Como listar todos os índices compostos

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

project-id: ID do projeto

Método HTTP e URL:

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

Para enviar a solicitação, 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

APIs Explorer

Você receberá uma resposta JSON semelhante a esta:

{
 "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"
  }
 ]
}