Configurazione degli indici con l'API REST

Questa pagina descrive come creare, eliminare ed elencare la modalità Datastore indici composti usando l'API REST in modalità Datastore.

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 il comando 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 metodi di indicizzazione, assegna uno dei seguenti ruoli IAM (Identity and Access Management):

  • 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 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 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

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

Explorer API

Copia il corpo della richiesta e apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Incolla il corpo della richiesta in questo strumento, compila tutti 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"
  }
}

Recupero dello stato dell'indice in corso...

La modalità Datastore assegna a ogni indice un ID 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

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 l'app pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Compila tutti 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

Consulta 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 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

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 l'app pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Compila tutti 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 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

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 l'app pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer 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"
  }
 ]
}