Configura índices con la API de REST

En esta página, se describe cómo crear, borrar y enumerar índices compuestos en modo Datastore con la API de REST en modo Datastore.

Google Cloud CLI proporciona una forma conveniente de acceder a la API de REST en modo Datastore y administrar tus índices compuestos. Sin embargo, puedes acceder directamente a la API de REST en modo Datastore a fin de crear tus propias herramientas para administrar los índices compuestos. Por ejemplo, puedes crear herramientas para automatizar el aprovisionamiento y la administración de índices.

Autenticación y autorización

A fin de acceder a los métodos de la API de REST de Firestore en modo Datastore que se encuentran a continuación, debes autenticar tu solicitud. Para ello, proporciona un token de acceso de Google OAuth 2.0 con uno de los siguientes permisos:

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

Los siguientes ejemplos de cURL y PowerShell usan el comando gcloud auth print-access-token para autenticar solicitudes. A fin de acceder a más información sobre cómo obtener un token de acceso, consulta la sección sobre Usa OAuth 2.0 para acceder a las API de Google.

Autorización

El usuario, el grupo o la cuenta de servicio con autenticación de la solicitud debe tener autorización para acceder a los métodos de la API. Para autorizar el acceso a los métodos de indexación, asigna una de las siguientes funciones de administración de identidades y accesos (IAM):

  • Para obtener acceso completo de lectura y edición de índices, otorga una de estas funciones:

    • roles/owner
    • roles/editor
    • roles/datastore.owner
    • roles/datastore.indexAdmin

  • Para el acceso de solo lectura de índices (get y list), otorga una de estas funciones:

    • roles/viewer
    • roles/datastore.user
    • roles/datastore.viewer

Para obtener más información sobre cómo asignar estas funciones, consulta Otorga, cambia y revoca el acceso a los recursos.

Antes de comenzar

En los ejemplos de curl y PowerShell que aparecen a continuación, se usa Google Cloud CLI (Google Cloud CLI) para autenticar solicitudes. Para ejecutar estos ejemplos de forma local, instala e inicializa Google Cloud CLI.

Como alternativa, puedes acceder a gcloud y curl desde la consola de Google Cloud mediante Cloud Shell.

Inicia Cloud Shell.

Crea un índice compuesto

Para crear un índice compuesto nuevo, usa el método projects.indexes.create.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: el ID de tu proyecto
  • kind: Es el tipo de entidad que se indexará.
  • include-ancestors: Indica si se deben incluir o no las entidades principales en el índice para admitir consultas principales, ya sea NONE o ALL_ANCESTORS.
  • property-name: Es la propiedad que se indexará; debe especificar dos o más propiedades.
  • index-direction: Es el orden de clasificación para cada propiedad, ASCENDING o DESCENDING.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de APIs se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Obtén el estado del índice

El modo Datastore le otorga a cada índice un ID de índice único. Puedes usar este ID de índice para obtener el estado de un índice único con el método projects.indexes.get:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: el ID de tu proyecto
  • index-id: Es un ID de índice compuesto.

Método HTTP y URL: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando: 

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

PowerShell

Ejecuta el siguiente 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

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Estado del índice

Consulta el estado del índice para obtener información sobre el progreso y mensajes de error. No puedes usar un índice para las consultas hasta que alcance el estado READY. Los estados del índice posibles son los siguientes:

  • CREATING: La creación del índice está en curso.
  • ALREADY_EXISTS: No se puede completar la operación porque este índice ya existe.
  • ERROR: Se produjo un error en la creación del índice. Corrige los datos que causaron el error, borra este índice y, luego, crea de nuevo el índice.
  • READY: Se completó la creación del índice. El índice está listo para usarlo en las consultas.

Borra un índice compuesto

Método HTTP y URL: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando: 

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

PowerShell

Ejecuta el siguiente 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

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.

Muestra todos los índices compuestos

A fin de enumerar todos los índices compuestos para una base de datos en modo Datastore, usa el método projects.indexes.list.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: el ID de tu proyecto

Método HTTP y URL: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando: 

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

PowerShell

Ejecuta el siguiente 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

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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