Configurazione degli indici con l'API REST

Google Cloud CLI offre un modo pratico per accedere l'API REST in modalità Datastore e gestire gli indici composti. Tuttavia, puoi accedere direttamente all'API REST in modalità Datastore per creare strumenti personalizzati per la gestione degli indici composti. Ad esempio, puoi creare strumenti per automatizzare il provisioning e la gestione degli indici.

Autenticazione e autorizzazione

Per accedere ai metodi dell'API REST di Firestore in modalità Datastore riportati di seguito, devi autenticare la richiesta fornendo un token di accesso Google OAuth 2.0 con uno dei seguenti ambiti:

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

Gli esempi di cURL e PowerShell riportati di seguito utilizzano gcloud auth print-access-token per autenticare le richieste. Per ulteriori informazioni informazioni su come ottenere un token di accesso, consulta Utilizzo di OAuth 2.0 per accedere alle API di Google.

Autorizzazione

L'utente, il gruppo o l'account di servizio autenticato nella richiesta devono disporre dell'autorizzazione per accedere ai metodi dell'API. Per autorizzare l'accesso ai di indicizzazione, assegna uno dei seguenti Identity and Access Management (IAM) ruoli:

• Per l'accesso completo in lettura e modifica all'indice, concedi uno di questi ruoli:

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

• Per solo l'accesso in lettura all'indice (get e list), concedi uno di questi ruoli:

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

Per ulteriori informazioni sull'assegnazione di questi ruoli, consulta concedere, modificare e revocare l'accesso alle risorse.

Prima di iniziare

Gli esempi di curl e PowerShell riportati di seguito utilizzano Google Cloud CLI (Google Cloud CLI) per autenticare le richieste. Per eseguire questi esempi in locale, installare e inizializzare Google Cloud CLI.

In alternativa, puoi accedere a gcloud e curl dal Console Google Cloud utilizzando Cloud Shell.

Avvia Cloud Shell

Creazione di un indice composto

Per creare un nuovo indice composto, utilizza il metodo projects.indexes.create.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

• project-id: il tuo ID progetto
• kind: il tipo di entità da indicizzare
• include-ancestors: se includere o meno i predecessori dell'entità nell'indice per supportare le query predecessori, NONE o ALL_ANCESTORS
• property-name: la proprietà da indicizzare deve specificare due o più proprietà
• index-direction: l'ordinamento per ogni proprietà, ASCENDING o DESCENDING

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

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"

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Recupero dello stato dell'indice in corso...

La modalità Datastore assegna a ogni indice un ID indice univoco. Puoi utilizzare questo ID indice per ottenere lo stato di un singolo indice con Metodo projects.indexes.get:

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

• project-id: il tuo ID progetto
• index-id: un ID indice composto

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

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

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Stato dell'indice

Controlla lo stato dell'indice per informazioni sull'avanzamento e messaggi di errore. Non puoi utilizzare un indice per le query finché non raggiunge la READY. I possibili stati dell'indice sono:

• CREATING: creazione dell'indice in corso.
• ALREADY_EXISTS: impossibile completare l'operazione perché questo indice esiste già.
• ERROR: creazione dell'indice non riuscita. Correggi i dati che hanno causato l'errore, elimina l'indice e poi crea di nuovo l'indice.
• READY: creazione dell'indice completata. L'indice è pronto per essere utilizzato per le query.

Eliminazione di un indice composto

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

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

$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

Dovresti ricevere un codice di stato di operazione riuscita (2xx) e una risposta vuota.

Elenco di tutti gli indici composti

per elencare tutti gli indici composti per l'utilizzo dei database in modalità Datastore il metodo projects.indexes.list.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

• project-id: il tuo ID progetto

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

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

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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