Utiliser des réservations d'emplacements

L'API BigQuery Reservation vous permet d'acheter des emplacements dédiés (nommés engagements), de créer des pools d'emplacements (nommés réservations), puis d'attribuer des projets, des dossiers et des organisations à ces réservations.

Les réservations vous permettent d'attribuer un nombre d'emplacements dédiés à une charge de travail. Par exemple, vous ne souhaitez peut-être pas qu'une charge de travail de production soit en concurrence avec les charges de travail de test pour les emplacements. Vous pouvez créer une réservation nommée prod et lui attribuer vos charges de travail de production. Pour en savoir plus, consultez la section Réservations.

Créer des réservations

Autorisations requises

Pour créer une réservation, vous devez disposer de l'autorisation Identity and Access Management (IAM) suivante :

bigquery.reservations.create sur le projet d'administration qui gère la propriété des engagements.

Tous les rôles IAM prédéfinis ci-dessous incluent cette autorisation :

BigQuery Resource Editor
BigQuery Resource Admin

Pour en savoir plus sur les rôles IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Créer une réservation avec des emplacements dédiés

Sélectionnez l'une des options suivantes :

Console

Dans la console Google Cloud, accédez à la page "BigQuery".

Accéder à BigQuery
Dans le panneau de navigation, accédez à la section Gestion de la capacité, puis cliquez sur Créer une réservation.
Dans le champ Nom de la réservation, saisissez un nom pour la réservation.
Dans la liste déroulante Emplacement, sélectionnez l'emplacement. Si vous sélectionnez un emplacement BigQuery Omni, votre option d'édition est limitée à l'édition Enterprise.
Dans la liste Édition, sélectionnez l'édition. L'autoscaling n'est disponible que dans une édition. Pour en savoir plus, consultez la page Présentation des éditions BigQuery.
Dans la liste Sélecteur de taille de réservation maximale, sélectionnez la taille de réservation maximale.
Facultatif : dans le champ Emplacements de référence, saisissez le nombre d'emplacements de référence pour la réservation.

Le nombre d'emplacements d'autoscaling disponibles est déterminé en soustrayant la valeur Emplacements de référence de la taille maximale de réservation. Par exemple, si vous créez une réservation avec 100 emplacements de référence et une taille de réservation maximale de 400, votre réservation comporte 300 emplacements d'autoscaling. Pour en savoir plus sur les emplacements de référence, consultez la section Utiliser des réservations avec des emplacements de référence et d'autoscaling.
Pour désactiver le partage d'emplacements inactifs et n'utiliser que la capacité d'emplacements spécifiée, cliquez sur le bouton Ignorer les emplacements inactifs.
Pour développer la section Paramètres avancés, cliquez sur la flèche de développement .
Facultatif : pour définir la simultanéité de job cible, cliquez sur le bouton Ignorer la simultanéité de job cible automatique et accédez à la simultanéité de job cible.
La répartition des emplacements est affichée dans le tableau Estimation des coûts. Un résumé de la réservation est affiché dans le tableau Récapitulatif de la capacité.
Cliquez sur Enregistrer.

La nouvelle réservation est visible dans l'onglet Réservations d'emplacements.

SQL

Pour créer une réservation, utilisez l'instruction LDD CREATE RESERVATION.

Dans Google Cloud Console, accédez à la page BigQuery.

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
CREATE RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
OPTIONS (
  slot_capacity = NUMBER_OF_BASELINE_SLOTS,
  edition = EDITION,
  autoscale_max_slots = NUMBER_OF_AUTOSCALING_SLOTS);
```
Remplacez les éléments suivants :
- ADMIN_PROJECT_ID : ID du projet d'administration propriétaire de la ressource de réservation
- LOCATION : emplacement de la réservation. Si vous sélectionnez un emplacement BigQuery Omni, votre option d'édition est limitée à l'édition Enterprise.
- RESERVATION_NAME : nom de la réservation
  
  Il doit commencer et se terminer par une lettre minuscule ou un chiffre, et ne contenir que des lettres minuscules, des chiffres et des tirets.
- NUMBER_OF_BASELINE_SLOTS : nombre d'emplacements de référence à allouer à la réservation. Vous ne pouvez pas définir les options slot_capacity et edition dans la même réservation.
- EDITION : édition de la réservation. L'attribution d'une réservation à une édition entraîne des modifications des fonctionnalités et des tarifs. Pour en savoir plus, consultez la page Présentation des éditions BigQuery.
- NUMBER_OF_AUTOSCALING_SLOTS : nombre d'emplacements d'autoscaling attribués à la réservation. Il est égal à la valeur de la taille de réservation maximale moins le nombre d'emplacements de référence.
Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Pour créer une réservation, exécutez la commande bq mk avec l'option --reservation :

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation \
    --slots=NUMBER_OF_BASELINE_SLOTS \
    --ignore_idle_slots=false \
    --edition=EDITION \
    --autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS \
    RESERVATION_NAME

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : ID du projet
LOCATION : emplacement de la réservation. Si vous sélectionnez un emplacement BigQuery Omni, votre option d'édition est limitée à l'édition Enterprise.
NUMBER_OF_BASELINE_SLOTS : nombre d'emplacements de référence à allouer à la réservation
RESERVATION_NAME : nom de la réservation.
EDITION : édition de la réservation. L'attribution d'une réservation à une édition entraîne des modifications des fonctionnalités et des tarifs. Pour en savoir plus, consultez la page Présentation des éditions BigQuery.
NUMBER_OF_AUTOSCALING_SLOTS : nombre d'emplacements d'autoscaling attribués à la réservation. Il est égal à la valeur de la taille de réservation maximale moins le nombre d'emplacements de référence.

Pour en savoir plus sur l'option --ignore_idle_slots, consultez la section Emplacements inactifs. La valeur par défaut est false.

Terraform

Utilisez la ressource google_bigquery_reservation.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant crée une réservation nommée my-reservation :

resource "google_bigquery_reservation" "default" {
  name              = "my-reservation"
  location          = "us-central1"
  slot_capacity     = 100
  edition           = "ENTERPRISE"
  ignore_idle_slots = false # Use idle slots from other reservations
  concurrency       = 0     # Automatically adjust query concurrency based on available resources
  autoscale {
    max_slots = 200 # Allow the reservation to scale up to 300 slots (slot_capacity + max_slots) if needed
  }
}

Pour appliquer votre configuration Terraform dans un projet Google Cloud, suivez les procédures des sections suivantes.

Préparer Cloud Shell

Lancez Cloud Shell.
Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.
Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
Enregistrez les modifications.
Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire.
```
terraform init
```
Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade :
```
terraform init -upgrade
```

Appliquer les modifications

Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes :
```
terraform plan
```
Corrigez les modifications de la configuration si nécessaire.
Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité :
```
terraform apply
```
Attendez que Terraform affiche le message "Apply completed!" (Application terminée).
Ouvrez votre projet Google Cloud pour afficher les résultats. Dans la console Google Cloud, accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

Python

Installez le package google-cloud-bigquery-reservation avant d'utiliser cet exemple de code. Créez un ReservationServiceClient. Décrivez la réservation que vous souhaitez créer dans un objet Reservation. Créez la réservation avec la méthode create_reservation.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Set slot_capicity to the number of slots in the
# reservation.
slot_capacity = 100

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service
from google.cloud.bigquery_reservation_v1.types import (
    reservation as reservation_types,
)

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)

parent = reservation_client.common_location_path(project_id, location)

reservation = reservation_types.Reservation(slot_capacity=slot_capacity)
reservation = reservation_client.create_reservation(
    parent=parent,
    reservation=reservation,
    reservation_id=reservation_id,
)

print(f"Created reservation: {reservation.name}")

Mettre à jour des réservations

Vous pouvez effectuer les mises à jour suivantes d'une réservation :

Modifiez la taille de la réservation en ajoutant ou en supprimant des emplacements.
Configurez si les requêtes de cette réservation utilisent les emplacements inactifs.
Modifiez la quantité d'emplacements de référence ou d'autoscaling alloués à une réservation.
Définissez la simultanéité de la tâche cible.

Pour modifier l'édition d'une réservation, commencez par supprimer la réservation, puis créez une réservation avec l'édition mise à jour.

Autorisations requises

Pour mettre à jour une réservation, vous devez disposer de l'autorisation Identity and Access Management (IAM) suivante :

bigquery.reservations.update sur le projet d'administration qui gère la propriété des engagements.

Tous les rôles IAM prédéfinis ci-dessous incluent cette autorisation :

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

Pour en savoir plus sur les rôles IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Modifier la taille d'une réservation

Vous pouvez ajouter ou supprimer des emplacements dans une réservation existante.

Console

Dans la console Google Cloud, accédez à la page "BigQuery".

Accéder à BigQuery
Dans le panneau de navigation, accédez à la section Gestion de la capacité.
Cliquez sur l'onglet Réservations d'emplacements.
Recherchez la réservation que vous souhaitez mettre à jour.
Développez l'option Actions.
Cliquez sur Modifier.
Dans la boîte de dialogue Taille maximale de la réservation, saisissez la taille maximale de la réservation.
Dans le champ Emplacements de référence, saisissez le nombre d'emplacements de référence.
Pour développer la section Paramètres avancés, cliquez sur la flèche de développement .
Facultatif : pour définir la simultanéité de job cible, cliquez sur le bouton Ignorer la simultanéité de job cible automatique et accédez à la simultanéité de job cible.
Cliquez sur Enregistrer.

SQL

Pour modifier la taille d'une réservation, utilisez l'instruction LDD (langage de définition de données) ALTER RESERVATION SET OPTIONS.

Dans la console Google Cloud, accédez à la page BigQuery.

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
ALTER RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
SET OPTIONS (
  slot_capacity = NUMBER_OF_BASELINE_SLOTS,
  autoscale_max_slots = NUMBER_OF_AUTOSCALING_SLOTS);
```
Remplacez les éléments suivants :
- ADMIN_PROJECT_ID : ID du projet d'administration propriétaire de la ressource de réservation
- LOCATION : emplacement de la réservation, par exemple europe-west9.
- RESERVATION_NAME : nom de la réservation. Il doit commencer et se terminer par une lettre minuscule ou un chiffre, et ne contenir que des lettres minuscules, des chiffres et des tirets.
- NUMBER_OF_BASELINE_SLOTS : nombre d'emplacements de référence à allouer à la réservation.
- NUMBER_OF_AUTOSCALING_SLOTS : nombre d'emplacements d'autoscaling attribués à la réservation. Il est égal à la valeur de la taille de réservation maximale moins le nombre d'emplacements de référence.
Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Pour mettre à jour la taille d'une réservation, utilisez la commande bq update avec l'option --reservation :

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --slots=NUMBER_OF_BASELINE_SLOTS \
    --autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS \
    --reservation RESERVATION_NAME

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : ID du projet
LOCATION : emplacement de la réservation.
NUMBER_OF_BASELINE_SLOTS : nombre d'emplacements de référence à allouer à la réservation
RESERVATION_NAME : nom de la réservation.
NUMBER_OF_AUTOSCALING_SLOTS : nombre d'emplacements d'autoscaling attribués à la réservation. Il est égal à la valeur de la taille de réservation maximale moins le nombre d'emplacements de référence.

Python

Installez le package google-cloud-bigquery-reservation avant d'utiliser cet exemple de code. Créez un ReservationServiceClient. Décrivez les propriétés mises à jour avec une réservation et la propriété FieldMask.paths. Mettez à jour la réservation avec la méthode update_reservation.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Set slot_capicity to the new number of slots in the
# reservation.
slot_capacity = 50

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service
from google.cloud.bigquery_reservation_v1.types import (
    reservation as reservation_types,
)
from google.protobuf import field_mask_pb2

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)

reservation_name = reservation_client.reservation_path(
    project_id, location, reservation_id
)
reservation = reservation_types.Reservation(
    name=reservation_name,
    slot_capacity=slot_capacity,
)
field_mask = field_mask_pb2.FieldMask(paths=["slot_capacity"])
reservation = reservation_client.update_reservation(
    reservation=reservation, update_mask=field_mask
)

print(f"Updated reservation: {reservation.name}")
print(f"\tslot_capacity: {reservation.slot_capacity}")

Configurer l'utilisation des emplacements inactifs pour les requêtes

L'option --ignore_idle_slots détermine si les requêtes exécutées dans une réservation peuvent utiliser des emplacements inactifs d'autres réservations. Pour en savoir plus, consultez la section Emplacements inactifs. Vous pouvez mettre à jour cette configuration sur une réservation existante.

Pour mettre à jour une réservation, exécutez la commande bq update avec l'option --reservation. L'exemple suivant définit --ignore_idle_slots sur true, ce qui signifie que la réservation n'utilisera que les emplacements alloués à la réservation.

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --ignore_idle_slots=true \
    --reservation RESERVATION_NAME

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : ID du projet
LOCATION : emplacement de la réservation
RESERVATION_NAME : nom de la réservation.

Répertorier la configuration des emplacements inactifs

Pour répertorier les paramètres des emplacements inactifs pour une réservation, procédez comme suit :

SQL

Interrogez la colonne ignore_idle_slots de la vue INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT.

Dans Google Cloud Console, accédez à la page BigQuery.

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
SELECT
  reservation_name,
  ignore_idle_slots
FROM
  `ADMIN_PROJECT_ID.region-LOCATION`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT;
```
Remplacez les éléments suivants :
- ADMIN_PROJECT_ID : ID du projet d'administration propriétaire des ressources de réservation
- LOCATION : emplacement des réservations
Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Exécutez la commande bq ls avec l'option --reservation :

bq ls --reservation \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : ID du projet d'administration propriétaire des ressources de réservation
LOCATION : emplacement des réservations

Le champ ignoreIdleSlots contient le paramètre de configuration.

Supprimer des réservations

Lorsque vous supprimez une réservation, toutes les tâches en cours d'exécution avec des emplacements de cette réservation échouent. Pour éviter les erreurs, attendez la fin de l'exécution des tâches en cours avant de supprimer la réservation.

Autorisations requises

Pour supprimer une réservation, vous devez disposer de l'autorisation IAM (Identity and Access Management) suivante :

bigquery.reservations.delete sur le projet d'administration qui gère la propriété des engagements.

Tous les rôles IAM prédéfinis ci-dessous incluent cette autorisation :

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

Pour en savoir plus sur les rôles IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Supprimer une réservation

Console

Dans la console Google Cloud, accédez à la page "BigQuery".

Accéder à BigQuery
Dans le panneau de navigation, accédez à la section Gestion de la capacité.
Cliquez sur l'onglet Réservations.
Recherchez la réservation que vous souhaitez supprimer.
Développez l'option Actions.
Cliquez sur Supprimer.
Dans la boîte de dialogue Supprimer la réservation, cliquez sur Supprimer.

SQL

Pour supprimer une réservation, utilisez l'instruction LDD DROP RESERVATION.

Dans Google Cloud Console, accédez à la page BigQuery.

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
DROP RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`;
```
Remplacez les éléments suivants :
- ADMIN_PROJECT_ID : ID du projet d'administration propriétaire de la ressource de réservation
- LOCATION : emplacement de la réservation.
- RESERVATION_NAME : ID de la réservation.
Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Pour supprimer une réservation, exécutez la commande bq rm avec l'option --reservation :

bq rm \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation RESERVATION_NAME

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : ID du projet d'administration propriétaire de la ressource de réservation
LOCATION : emplacement de la réservation.
RESERVATION_NAME : nom de la réservation.

Python

Installez le package google-cloud-bigquery-reservation avant d'utiliser cet exemple de code. Créez un ReservationServiceClient. Supprimez la réservation avec la méthode delete_reservation.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)
reservation_name = reservation_client.reservation_path(
    project_id, location, reservation_id
)
reservation_client.delete_reservation(name=reservation_name)

print(f"Deleted reservation: {reservation_name}")