Utiliser les anciennes 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 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.

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é.
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.
Dans la section Modèle de capacité, choisissez le modèle de capacité.
Si vous sélectionnez l'option Tarif forfaitaire, sous Emplacements de référence, saisissez le nombre d'emplacements pour la réservation.
1. Dans la liste Sélecteur de taille de réservation maximale, sélectionnez la taille de réservation maximale.
2. Facultatif : dans le champ Emplacements de référence, saisissez le nombre d'emplacements de référence pour la réservation. Pour n'utiliser que la capacité d'emplacements spécifiée, cliquez sur le bouton Ignorer les emplacements inactifs.
  
  La quantité d'emplacements d'autoscaling disponibles est déterminée en soustrayant la valeur des emplacements de référence de la valeur de taille maximale de la 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 des emplacements inactifs, cliquez sur le bouton Ignorer les emplacements inactifs.
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.

SQL

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

Dans la console Google Cloud, 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,
);
```
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 \
    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.

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.

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.
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.
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,
);
```
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.
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 \
    --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.

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 la console Google Cloud, 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 la console Google Cloud, 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}")

Ajouter l'API BigQuery Reservations à VPC Service Controls

L'API BigQuery Reservations est compatible avec VPC Service Controls. Pour intégrer l'API BigQuery Reservations à VPC Service Controls, suivez les instructions de la section Créer un périmètre de service et ajoutez l'API BigQuery Reservations aux services protégés.

Un périmètre de service protège l'accès aux réservations, aux engagements et aux attributions au sein des projets d'administration qui sont spécifiés dans le périmètre. Lors de la création d'une attribution, VPC Service Controls protège le projet d'administration ainsi que le projet, le dossier et l'organisation assignés.