Utiliser des attributions de réservation

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.

Créer des attributions de réservation

Pour utiliser les emplacements que vous achetez, vous devez créer une attribution qui attribue un projet, un dossier ou une organisation à une réservation d'emplacements.

Les projets utilisent la réservation la plus spécifique unique dans la hiérarchie des ressources à laquelle ils sont attribués. Une attribution de dossier remplace une attribution d'organisation, et une attribution de projet remplace une attribution de dossier. Les attributions de dossiers et d'organisations ne sont pas disponibles pour les réservations de l'édition standard.

Pour créer une attribution sur une réservation, celle-ci doit répondre à au moins l'un des critères suivants :

Le nombre d'emplacements de référence attribués est différent de zéro.
Le nombre d'emplacements d'autoscaling est différent de zéro.
Elle est configurée pour utiliser des emplacements inactifs, et des emplacements inactifs sont disponibles dans le projet.

Si vous essayez d'attribuer une ressource à une réservation qui ne répond pas à au moins l'un de ces critères, vous recevez le message suivant : Assignment is pending, your project will be executed as on-demand.

Vous pouvez attribuer une ressource à une réservation de basculement, mais l'attribution est conservée dans l'emplacement secondaire.

Autorisations requises

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

bigquery.reservationAssignments.create sur le projet d'administration et la personne responsable.

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.

Attribuer une organisation à 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 dans le tableau des réservations.
Développez l'option Actions.
Cliquez sur Créer une attribution.
Dans la section Créer une attribution, cliquez sur Parcourir.
Recherchez l'organisation et sélectionnez-la.
Dans la section Job Type (Type de tâche), sélectionnez un type de tâche à attribuer pour cette réservation. Vous avez le choix entre plusieurs options :
- QUERY
- CONTINUOUS
- PIPELINE
- BACKGROUND
- ML_EXTERNAL
Pour en savoir plus sur les types de tâches, consultez la section Attributions de réservation. Cette valeur par défaut est QUERY.
Cliquez sur Créer.

SQL

Pour attribuer une organisation à une réservation, utilisez l'instruction LDD CREATE ASSIGNMENT.

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

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
CREATE ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`
OPTIONS (
  assignee = 'organizations/ORGANIZATION_ID',
  job_type = 'JOB_TYPE');
```
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
- ASSIGNMENT_ID : ID de l'attribution
  
  L'ID doit être unique au projet et à l'emplacement. Il doit commencer et se terminer par une lettre minuscule ou un chiffre, et ne doit contenir que des lettres minuscules, des chiffres et des tirets.
- ORGANIZATION_ID : ID de l'organisation
- JOB_TYPE : type de job à attribuer à cette réservation, tel que QUERY, CONTINUOUS, PIPELINE, BACKGROUND ou ML_EXTERNAL
Cliquez sur Exécuter.

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

bq

Pour attribuer les tâches d'une organisation à une réservation, utilisez la commande bq mk avec l'option --reservation_assignment :

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --assignee_id=ORGANIZATION_ID \
    --job_type=JOB_TYPE \
    --assignee_type=ORGANIZATION

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
ORGANIZATION_ID : ID de l'organisation
JOB_TYPE : type de job à attribuer à cette réservation, tel que QUERY, CONTINUOUS, PIPELINE, BACKGROUND ou ML_EXTERNAL

Lorsque vous créez une attribution de réservation, attendez au moins cinq minutes avant d'exécuter une requête. Sinon, la requête risque d'être facturée au tarif à la demande.

Attribuer un projet ou un dossier à 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 dans le tableau des réservations.
Développez l'option Actions.
Cliquez sur Créer une attribution.
Dans la section Créer une attribution, cliquez sur Parcourir.
Recherchez le projet ou le dossier, puis sélectionnez-le.
Dans la section Job Type (Type de tâche), sélectionnez un type de tâche à attribuer pour cette réservation. Vous avez le choix entre plusieurs options :
- QUERY
- CONTINUOUS
- PIPELINE
- BACKGROUND
- ML_EXTERNAL
Pour en savoir plus sur les types de tâches, consultez la section Attributions de réservation. Cette valeur par défaut est QUERY.
Cliquez sur Créer.

SQL

Pour attribuer un projet à une réservation, utilisez l'instruction LDD CREATE ASSIGNMENT.

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

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
CREATE ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`
OPTIONS(
  assignee="projects/PROJECT_ID",
  job_type="JOB_TYPE");
```
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
- ASSIGNMENT_ID : ID de l'attribution
  
  L'ID doit être unique au projet et à l'emplacement. Il doit commencer et se terminer par une lettre minuscule ou un chiffre, et ne doit contenir que des lettres minuscules, des chiffres et des tirets.
- PROJECT_ID : ID du projet à attribuer à la réservation
- JOB_TYPE : type de job à attribuer à cette réservation, tel que QUERY, CONTINUOUS, PIPELINE, BACKGROUND ou ML_EXTERNAL
Cliquez sur Exécuter.

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

bq

Pour attribuer des tâches à une réservation, exécutez la commande bq mk avec l'option --reservation_assignment :

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --assignee_id=PROJECT_ID \
    --job_type=JOB_TYPE \
    --assignee_type=PROJECT

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
PROJECT_ID : ID du projet à attribuer à cette réservation
JOB_TYPE : type de job à attribuer à cette réservation, tel que QUERY, CONTINUOUS, PIPELINE, BACKGROUND ou ML_EXTERNAL

Terraform

Utilisez la ressource google_bigquery_reservation_assignment.

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 attribue un projet à la 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
  }
}

data "google_project" "project" {}

resource "google_bigquery_reservation_assignment" "default" {
  assignee    = "projects/${data.google_project.project.project_id}"
  job_type    = "QUERY"
  reservation = google_bigquery_reservation.default.id
}

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.

Lorsque vous créez une attribution de réservation, attendez au moins cinq minutes avant d'exécuter une requête. Sinon, la requête risque d'être facturée au tarif à la demande.

Pour créer un projet qui n'utilise que des emplacements inactifs, créez une réservation avec des emplacements 0 qui lui sont attribués, puis suivez les étapes précédentes nécessaires à l'attribution du projet à cette réservation.

Attribuer un projet à `none`

Les attributions none représentent l'absence d'attribution. Les projets dont l'attribution est none utilisent la tarification à la demande.

SQL

Pour attribuer un projet à none, utilisez l'instruction LDD CREATE ASSIGNMENT.

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

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
CREATE ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.none.ASSIGNMENT_ID`
OPTIONS(
  assignee="projects/PROJECT_ID",
  job_type="QUERY");
```
Remplacez les éléments suivants :
- LOCATION : emplacement des jobs qui doivent utiliser la tarification à la demande
- ASSIGNMENT_ID : ID de l'attribution
  
  L'ID doit être unique au projet et à l'emplacement. Il doit commencer et se terminer par une lettre minuscule ou un chiffre, et ne doit contenir que des lettres minuscules, des chiffres et des tirets.
- PROJECT_ID : ID du projet à attribuer à 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 attribuer un projet à none, utilisez la commande bq mk avec l'option --reservation_assignment :

bq mk \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=none \
    --job_type=QUERY \
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Remplacez les éléments suivants :

LOCATION : emplacement des jobs qui doivent utiliser la tarification à la demande
PROJECT_ID : ID du projet à attribuer à none

Attribuer des emplacements aux charges de travail BigQuery ML

Les types de modèles BigQuery ML suivants utilisent des services externes :

Vous pouvez attribuer des emplacements réservés aux requêtes à l'aide de ces services en utilisant le type d'attribution ML_EXTERNAL. Si aucun type d'attribution ML_EXTERNAL n'est trouvé, le job de requête s'exécute à la demande.

Exécutez la commande bq mk avec l'option --reservation_assignment, puis définissez l'option --job_type sur ML_EXTERNAL.

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --job_type=ML_EXTERNAL\
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : l'ID du projet propriétaire de la ressource de réservation
LOCATION : emplacement de la réservation
RESERVATION_NAME : nom de la réservation.
PROJECT_ID : ID du projet à attribuer à cette réservation

Rechercher des attributions de réservation

Autorisations requises

Pour rechercher une attribution de réservation pour un projet, un dossier ou une organisation donnée, vous avez besoin de l'autorisation Identity and Access Management (IAM) suivante :

bigquery.reservationAssignments.list sur le projet d'administration

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

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor
BigQuery Resource Viewer
BigQuery User

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

Rechercher une attribution de réservation pour un projet

Pour savoir si votre projet, dossier ou organisation est attribué à une réservation, procédez comme suit :

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.
Dans la table des réservations, développez une réservation pour afficher les ressources attribuées à cette réservation, ou utilisez le champ Filtrer pour filtrer par nom de ressource.

SQL

Pour trouver à quelle réservation les tâches de requête de votre projet sont attribuées, interrogez la vue INFORMATION_SCHEMA.ASSIGNMENTS_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
    assignment_id
  FROM `region-LOCATION`.INFORMATION_SCHEMA.ASSIGNMENTS_BY_PROJECT
  WHERE
    assignee_id = 'PROJECT_ID'
    AND job_type = 'JOB_TYPE';
```
Remplacez les éléments suivants :
- LOCATION : emplacement des réservations à afficher
- ADMIN_PROJECT_ID : ID du projet d'administration propriétaire de la ressource de réservation
- PROJECT_ID : ID du projet à attribuer à la réservation
- JOB_TYPE : type de job à attribuer à cette réservation, tel que QUERY, CONTINUOUS, PIPELINE, BACKGROUND ou ML_EXTERNAL
Cliquez sur Exécuter.

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

bq

Pour trouver à quelle réservation les tâches de requête de votre projet sont attribuées, utilisez la commande bq show avec l'option --reservation_assignment :

bq show \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --job_type=JOB_TYPE \
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : l'ID du projet propriétaire de la ressource de réservation
LOCATION : emplacement des réservations à afficher
JOB_TYPE : type de job à attribuer à cette réservation, tel que QUERY, CONTINUOUS, PIPELINE, BACKGROUND ou ML_EXTERNAL
PROJECT_ID : ID du projet

Mettre à jour les attributions de réservation

Déplacer une attribution vers une autre réservation

Vous pouvez déplacer une attribution d'une réservation à une autre.

Pour déplacer une attribution de réservation, vous devez disposer des autorisations IAM (Identity and Access Management) suivantes sur le projet d'administration et la personne responsable.

bigquery.reservationAssignments.create
bigquery.reservationAssignments.delete

Chacun des rôles IAM prédéfinis suivants inclut ces autorisations :

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.

Pour déplacer une attribution, utilisez la commande bq update :

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --destination_reservation_id=DESTINATION_RESERVATION \
    ADMIN_PROJECT_ID:LOCATION.RESERVATION_NAME.ASSIGNMENT_ID

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : l'ID du projet propriétaire de la ressource de réservation
LOCATION : emplacement de la nouvelle réservation
RESERVATION_NAME : réservation depuis laquelle déplacer l'attribution
DESTINATION_RESERVATION : réservation vers laquelle déplacer l'attribution
ASSIGNMENT_ID : ID de l'attribution

Pour obtenir l'ID d'attribution, consultez la section Répertorier une attribution de réservation d'un projet.

Supprimer les attributions de réservation

Vous pouvez supprimer un projet d'une réservation en supprimant l'attribution de réservation. Si un projet n'est attribué à aucune réservation, il hérite des attributions de ses dossiers ou organisations parents, ou alors utilise une tarification à la demande s'il n'y a pas d'attributions parentes.

Lorsque vous supprimez une attribution de réservation, les jobs exécutés avec des emplacements de cette réservation continuent de s'exécuter jusqu'à la fin.

Autorisations requises

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

bigquery.reservationAssignments.delete sur le projet d'administration et la personne responsable.

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

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

Supprimer un projet d'une réservation

Pour supprimer un projet d'une réservation, procédez comme suit :

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.
Dans la table des réservations, développez la réservation pour rechercher le projet.
Développez l'option Actions.
Cliquez sur Supprimer.

SQL

Utilisez l'instruction LDD DROP ASSIGNMENT :

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

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
DROP ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`;
```
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
- ASSIGNMENT_ID : ID de l'attribution
  
  Pour trouver l'ID d'attribution, consultez la section Répertorier une attribution de réservation d'un projet.
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 un projet d'une réservation, exécutez la commande bq rm avec l'option --reservation_assignment :

bq rm \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment RESERVATION_NAME.ASSIGNMENT_ID

Remplacez les éléments suivants :

ADMIN_PROJECT_ID : l'ID du projet propriétaire de la ressource de réservation
LOCATION : emplacement de la réservation
RESERVATION_NAME : nom de la réservation
ASSIGNMENT_ID : ID de l'attribution

Pour obtenir l'ID d'attribution, consultez la section Rechercher une attribution de réservation d'un projet.

Utiliser des attributions de réservation

Créer des attributions de réservation

Autorisations requises

Attribuer une organisation à une réservation

Console

SQL

bq

Attribuer un projet ou un dossier à une réservation

Console

SQL

bq

Terraform

Préparer Cloud Shell

Préparer le répertoire

Appliquer les modifications

Attribuer un projet à none

SQL

bq

Attribuer des emplacements aux charges de travail BigQuery ML

Rechercher des attributions de réservation

Autorisations requises

Rechercher une attribution de réservation pour un projet

Console

SQL

bq

Mettre à jour les attributions de réservation

Déplacer une attribution vers une autre réservation

Supprimer les attributions de réservation

Autorisations requises

Supprimer un projet d'une réservation

Console

SQL

bq

Attribuer un projet à `none`