Como configurar índices com a API REST

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

A Google Cloud CLI 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.

Inicie o 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, 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

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

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 projects.indexes.get:

Antes de usar os dados da solicitação, 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

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á 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, 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

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:

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