Configurer les index avec l'API REST

Cette page explique comment créer, supprimer et répertorier des index composites en mode Datastore à l'aide de l'API REST en mode Datastore.

La Google Cloud CLI permet d'accéder facilement à l'API REST en mode Datastore et de gérer vos index composites. Cependant, il est possible d'accéder directement à l'API REST en mode Datastore pour créer vos propres outils de gestion des index composites. Par exemple, vous pouvez créer des outils pour automatiser la gestion et le provisionnement d'index.

Authentification et autorisation

Pour accéder aux méthodes de l'API REST Firestore en mode Datastore ci-dessous, vous devez authentifier votre requête en fournissant un jeton d'accès Google OAuth 2.0 avec l'un des champs d'application suivants :

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

Les exemples cURL et PowerShell ci-dessous utilisent la commande gcloud auth print-access-token pour authentifier les requêtes. Pour plus d'informations sur l'obtention d'un jeton d'accès, consultez la section Utiliser OAuth 2.0 pour accéder aux API Google.

Autorisation

L'utilisateur, le groupe ou le compte de service authentifié dans la requête doit être autorisé à accéder aux méthodes d'API. Pour autoriser l'accès aux méthodes d'indexation, attribuez l'un des rôles IAM (Identity and Access Management) suivants :

  • Pour bénéficier d'un accès complet en lecture et en modification des index, attribuez l'un des rôles suivants :

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

  • Pour l'accès en lecture seule à l'index (get et list), attribuez l'un des rôles suivants :

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

Pour plus d'informations sur l'attribution de ces rôles, reportez-vous à la section Accorder, modifier et révoquer les accès aux ressources.

Avant de commencer

Les exemples curl et PowerShell ci-dessous utilisent la Google Cloud CLI (Google Cloud CLI) pour authentifier les requêtes. Pour exécuter ces exemples en local, installez et initialisez la Google Cloud CLI.

Vous pouvez également accéder à gcloud et à curl depuis la console Google Cloud à l'aide de Cloud Shell.

Démarrer Cloud Shell

Créer un index composite

Pour créer un index composite, utilisez la méthode projects.indexes.create.

Avant d'utiliser les données de requête, effectuez les remplacements suivants:

  • project-id : ID de votre projet.
  • kind : genre de l'entité à indexer
  • include-ancestors : inclusion ou non des ancêtres d'entités dans l'index afin d'accepter les requêtes d'ancêtre, soit NONE, soit ALL_ANCESTORS
  • property-name : propriété à indexer, doit spécifier deux ou plusieurs propriétés
  • index-direction : ordre de tri de chaque propriété, ASCENDING ou DESCENDING

Méthode HTTP et URL : 

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

Corps JSON de la requête : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json et exécutez la commande suivante: 

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

Enregistrez le corps de la requête dans un fichier nommé request.json et exécutez la commande suivante: 

$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

Copiez le corps de la requête et ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Collez le corps de la requête dans cet outil, renseignez tous les champs obligatoires, puis cliquez sur Execute (Exécuter).

Vous devriez recevoir une réponse JSON de ce type :

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

Obtenir l'état de l'index

Le mode Datastore attribue à chaque index un ID d'index unique. Cet ID d'index vous permet d'obtenir l'état d'un seul index avec la méthode projects.indexes.get :

Avant d'utiliser les données de requête, effectuez les remplacements suivants:

  • project-id : ID de votre projet.
  • index-id : un ID d'index composite

Méthode HTTP et URL : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

exécutez la commande suivante : 

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

PowerShell

exécutez la commande suivante : 

$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

Ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Renseignez tous les champs obligatoires, puis cliquez sur Exécuter.

Vous devriez recevoir une réponse JSON de ce type :

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

État de l'index

Consultez l'état de l'index pour afficher les informations de progression et les messages d'erreur. Vous ne pouvez pas utiliser un index pour les requêtes tant qu'il n'a pas atteint l'état READY. Les états d'index possibles sont les suivants :

  • CREATING : création d'index en cours.
  • ALREADY_EXISTS : impossible d'effectuer l'opération, car cet index existe déjà.
  • ERROR : échec de la création de l'index. Corrigez les données à l'origine de l'erreur, supprimez cet index, puis créez l'index à nouveau.
  • READY : création de l'index terminée. L'index est prêt à être utilisé pour les requêtes.

Supprimer un index composite

Méthode HTTP et URL : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

exécutez la commande suivante : 

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

PowerShell

exécutez la commande suivante : 

$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

Ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Renseignez tous les champs obligatoires, puis cliquez sur Exécuter.

Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.

Répertorier tous les index composites

Pour répertorier tous les index composites d'une base de données en mode Datastore, utilisez la méthode projects.indexes.list.

Avant d'utiliser les données de requête, effectuez les remplacements suivants:

  • project-id : ID de votre projet.

Méthode HTTP et URL : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

exécutez la commande suivante : 

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

PowerShell

exécutez la commande suivante : 

$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

Ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Renseignez tous les champs obligatoires, puis cliquez sur Exécuter.

Vous devriez recevoir une réponse JSON de ce type :

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