Configurazione degli indici con l'API REST

Questa pagina descrive come creare, eliminare ed elencare gli indici compositi in modalità Datastore utilizzando l'API REST in modalità Datastore.

La CLI Google Cloud offre un modo pratico per accedere all'API REST in modalità Datastore e gestire gli indici compositi. Tuttavia, puoi accedere direttamente all'API REST in modalità Datastore per creare i tuoi strumenti per la gestione degli indici compositi. 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 OAuth 2.0 di Google 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 il comando gcloud auth print-access-token per autenticare le richieste. Per ulteriori informazioni su come ottenere un token di accesso, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

Autorizzazione

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

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

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

  • Per l'accesso di sola 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 la sezione relativa alla concessione, alla modifica e alla revoca dell'accesso alle risorse.

Prima di iniziare

Gli esempi curl e PowerShell riportati di seguito utilizzano Google Cloud CLI (Google Cloud CLI) per autenticare le richieste. Per eseguire questi esempi localmente, installa e inizializza Google Cloud CLI.

In alternativa, puoi accedere a gcloud e curl dalla console Google Cloud utilizzando Cloud Shell.

Avvia Cloud Shell

Creazione di un indice composto

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

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

  • project-id: il tuo ID progetto
  • kind: il tipo di entità da indicizzare
  • include-ancestors: indica se includere o meno gli antenati delle entità nell'indice per supportare le query da predecessore, NONE o ALL_ANCESTORS
  • property-name: la proprietà da indicizzare, devono essere specificate due o più proprietà
  • index-direction: l'ordine di 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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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

Explorer API

Copia il corpo della richiesta e apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Esplora API. Puoi interagire con questo strumento per inviare richieste. Incolla il corpo della richiesta in questo strumento, compila gli altri campi obbligatori e fai clic su Esegui.

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

Stato dell'indice

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

Prima di utilizzare i dati della richiesta, apporta 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

Esegui questo comando: 

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

PowerShell

Esegui questo 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

Explorer API

Apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Esplora API. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

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 su messaggi di errore. Non puoi utilizzare un indice per le query finché non raggiunge lo stato READY. Gli stati possibili 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 crealo di nuovo.
  • 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

Esegui questo comando: 

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

PowerShell

Esegui questo 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

Explorer API

Apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Esplora API. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

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 un database in modalità Datastore, utilizza il metodo projects.indexes.list.

Prima di utilizzare i dati della richiesta, apporta 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

Esegui questo comando: 

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

PowerShell

Esegui questo 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

Explorer API

Apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Esplora API. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

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