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 en attente à 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 :

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

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

    Accéder à BigQuery

  2. Dans le panneau de navigation, accédez à la section Gestion de la capacité.

  3. Cliquez sur l'onglet Réservations.

  4. Recherchez la réservation dans le tableau des réservations.

  5. Développez l'option Actions.

  6. Cliquez sur Créer une attribution.

  7. Dans la section Créer une attribution, cliquez sur Parcourir.

  8. Recherchez l'organisation et sélectionnez-la.

  9. 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 (bêta)
    • 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.

  10. Cliquez sur Créer.

SQL

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

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

    Accéder à BigQuery

  2. 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 (version bêta), PIPELINE, BACKGROUND ou ML_EXTERNAL

  3. 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 :

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

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

    Accéder à BigQuery

  2. Dans le panneau de navigation, accédez à la section Gestion de la capacité.

  3. Cliquez sur l'onglet Réservations.

  4. Recherchez la réservation dans le tableau des réservations.

  5. Développez l'option Actions.

  6. Cliquez sur Créer une attribution.

  7. Dans la section Créer une attribution, cliquez sur Parcourir.

  8. Recherchez le projet ou le dossier, puis sélectionnez-le.

  9. 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 (bêta)
    • 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.

  10. Cliquez sur Créer.

SQL

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

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

    Accéder à BigQuery

  2. 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 (version bêta), PIPELINE, BACKGROUND ou ML_EXTERNAL

  3. 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 (version bêta), 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

  1. Lancez Cloud Shell.
  2. 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).

  1. 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
  2. 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.

  3. Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
  4. Enregistrez les modifications.
  5. 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

  1. 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.

  2. 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).

  3. 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.

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

    Accéder à BigQuery

  2. 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

  3. 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

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

    Accéder à BigQuery

  2. Dans le panneau de navigation, accédez à la section Gestion de la capacité.

  3. Cliquez sur l'onglet Réservations.

  4. 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.

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

    Accéder à BigQuery

  2. 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 (version bêta), PIPELINE, BACKGROUND ou ML_EXTERNAL

  3. 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 (version bêta), 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 :

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

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

    Accéder à BigQuery

  2. Dans le panneau de navigation, accédez à la section Gestion de la capacité.

  3. Cliquez sur l'onglet Réservations.

  4. Dans la table des réservations, développez la réservation pour rechercher le projet.

  5. Développez l'option Actions.

  6. Cliquez sur Supprimer.

SQL

Utilisez l'instruction LDD DROP ASSIGNMENT :

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

    Accéder à BigQuery

  2. 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 :

  3. 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 :