Utiliser des fonctions distantes

Une fonction distante BigQuery vous permet de mettre en œuvre votre fonction dans d'autres langages que SQL et JavaScript, ou avec des bibliothèques ou services non autorisés dans les fonctions définies par l'utilisateur BigQuery.

Présentation

Une fonction distante BigQuery vous permet d'intégrer des fonctionnalités GoogleSQL dans des logiciels externes à BigQuery grâce à une intégration directe de fonctions Cloud Run et Cloud Run. Avec les fonctions à distance de BigQuery, vous pouvez déployer vos fonctions dans les fonctions Cloud Run ou Cloud Run en utilisant n'importe quel langage compatible, puis les appeler à partir de requêtes GoogleSQL.

Workflow

  1. Créez le point de terminaison HTTP dans les fonctions Cloud Run ou Cloud Run.
  2. Créez une fonction distante dans BigQuery.
    1. Créez une connexion de type CLOUD_RESOURCE.
    2. Créez une fonction distante.
  3. Utilisez la fonction distante dans une requête comme n'importe quelle autre fonction définie par l'utilisateur.

Limites

  • Les fonctions distantes ne sont compatibles qu'avec l'un des types de données suivants, en tant que type d'argument ou type renvoyé :

    • Booléen
    • Octets
    • Numérique
    • Chaîne
    • Date
    • Date/Heure
    • Heure
    • Horodatage
    • JSON

    Les fonctions distantes ne sont pas compatibles avec les types ARRAY, STRUCT, INTERVAL ou GEOGRAPHY.

  • Vous ne pouvez pas créer de fonctions distantes temporaires.

  • Vous ne pouvez pas créer de fonctions distantes basées sur des valeurs de table.

  • Vous ne pouvez pas utiliser de fonctions distantes lors de la création de vues matérialisées.

  • La valeur renvoyée par une fonction distante est toujours considérée comme non déterministe. Par conséquent, le résultat d'une requête appelant une fonction distante n'est pas mis en cache.

  • Des requêtes répétées avec les mêmes données vers votre point de terminaison peuvent s'afficher, même après des réponses réussies, en raison d'erreurs réseau temporaires ou d'erreurs internes BigQuery.

  • Lorsqu'une évaluation de fonction distante est ignorée pour certaines lignes en raison d'un court-circuit, par exemple, dans Expressions conditionnelles ou une instruction MERGE avec WHEN [NOT] MATCHED, le traitement par lot n'est pas utilisé avec la fonction distante. Dans ce cas, le champ calls du corps de la requête HTTP contient exactement un élément.

  • Si l'ensemble de données associé à la fonction distante est répliqué dans une région de destination via la réplication interrégionale d'ensembles de données, la fonction distante ne peut être interrogée que dans la région dans laquelle il a été créé.

Créer un point de terminaison

Pour créer une fonction distante capable de mettre en œuvre une logique métier, vous devez créer un point de terminaison HTTP à l'aide de fonctions Cloud Run ou de Cloud Run. Le point de terminaison doit pouvoir traiter un lot de lignes dans une seule requête HTTP POST et renvoyer les résultats du lot sous forme de réponse HTTP.

Si vous créez la fonction distante à l'aide de BigQuery DataFrames, vous n'avez pas besoin de créer manuellement le point de terminaison HTTP. Le service le fait automatiquement.

Consultez le tutoriel sur les fonctions Cloud Run et la documentation sur les fonctions Cloud Run pour découvrir comment écrire, déployer, tester et gérer une fonction Cloud Run.

Consultez le guide de démarrage rapide de Cloud Run et les autres documents sur Cloud Run pour savoir comment écrire, déployer, tester et gérer un service Cloud Run.

Il est recommandé de conserver l'authentification par défaut au lieu d'autoriser les appels non authentifiés de votre fonction Cloud Run ou de votre service Cloud Run.

Format d'entrée

BigQuery envoie des requêtes HTTP POST avec un corps JSON au format suivant :

Nom du champ Description Type de champ
requestId ID de la requête. Unique sur plusieurs requêtes envoyées à ce point de terminaison dans une requête GoogleSQL. Toujours fourni. Chaîne.
appelant Nom complet de la ressource de tâche pour la requête GoogleSQL appelant la fonction distante. Toujours fourni. Chaîne.
sessionUser Adresse e-mail de l'utilisateur exécutant la requête GoogleSQL. Toujours fourni. Chaîne.
userDefinedContext Contexte défini par l'utilisateur utilisé lors de la création de la fonction distante dans BigQuery. Facultatif. Objet JSON avec des paires clé/valeur.
calls Un lot de données d'entrée. Toujours fourni. Un tableau JSON.

Chaque élément lui-même est un tableau JSON, qui est une liste d'arguments encodés au format JSON d'un appel de fonction distante.

Exemple de requête :

{
 "requestId": "124ab1c",
 "caller": "//bigquery.googleapis.com/projects/myproject/jobs/myproject:US.bquxjob_5b4c112c_17961fafeaf",
 "sessionUser": "test-user@test-company.com",
 "userDefinedContext": {
  "key1": "value1",
  "key2": "v2"
 },
 "calls": [
  [null, 1, "", "abc"],
  ["abc", "9007199254740993", null, null]
 ]
}

Format de sortie

BigQuery s'attend à ce que le point de terminaison renvoie une réponse HTTP au format suivant. Sinon, BigQuery ne pourra pas la consommer et fera échouer la requête appelant la fonction distante.

Nom du champ Description Plage de valeurs
replies Un lot de valeurs de retour. Obligatoire pour une réponse positive. Un tableau JSON.

Chaque élément correspond à une valeur de retour de la fonction externe au format JSON.

La taille du tableau doit correspondre à celle du tableau JSON de calls dans la requête HTTP. Par exemple, si le tableau JSON dans calls contient quatre éléments, ce tableau JSON doit également contenir quatre éléments.

errorMessage Message d'erreur lorsqu'un code de réponse HTTP autre que 200 est renvoyé. Pour les erreurs ne permettant aucune autre tentative, nous le renvoyons dans le message d'erreur de la tâche BigQuery qui est envoyée à l'utilisateur. Facultatif. Chaîne. La taille doit être inférieure à 1 Ko.

Voici un exemple de réponse positive :

{
  "replies": [
    1,
    0
  ]
}

Exemple de réponse ayant échoué :

{
  "errorMessage": "Received but not expected that the argument 0 be null".
}

Code de réponse HTTP

Votre point de terminaison doit renvoyer le code de réponse HTTP 200 pour obtenir une réponse positive. Lorsque BigQuery reçoit une autre valeur, il considère la réponse comme un échec et effectue une nouvelle tentative lorsque le code de réponse HTTP est 408, 429, 500, 503 ou 504 jusqu'à une certaine limite interne.

Encodage JSON pour le type de données SQL

L'encodage JSON dans la requête/réponse HTTP suit l'encodage JSON BigQuery existant pour la fonction TO_JSON_STRING.

Exemple de code de fonction Cloud Run

L'exemple de code Python suivant met en œuvre l'ajout de tous les arguments entiers de la fonction distante. Il traite une requête avec les arguments des appels par lot et renvoie tous les résultats dans une réponse.

import functions_framework

from flask import jsonify

# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
# See https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_MAX_LOSSLESS=9007199254740992

@functions_framework.http
def batch_add(request):
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
    replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
    return_json = jsonify( { "replies":  replies } )
    return return_json
  except Exception as e:
    return jsonify( { "errorMessage": str(e) } ), 400

Si la fonction est déployée dans le projet my_gcf_project dans la région us-east1 avec le nom de fonction remote_add, alors elle est accessible via le point de terminaison https://us-east1-my_gcf_project.cloudfunctions.net/remote_add.

Exemple de code Cloud Run

L'exemple de code Python suivant implémente un service Web, qui peut être créé et déployé sur Cloud Run pour la même fonctionnalité.

import os

from flask import Flask, request, jsonify

# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
# See https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_MAX_LOSSLESS=9007199254740992

app = Flask(__name__)

@app.route("/", methods=['POST'])
def batch_add():
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
    replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
    return jsonify( { "replies" :  replies } )
  except Exception as e:
    return jsonify( { "errorMessage": str(e) } ), 400

if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

Consultez le guide de création et de déploiement du code.

Si le service Cloud Run est déployé dans le projet my_gcf_project dans la région us-east1 comme nom de service remote_add, il est accessible via le point de terminaison https://remote_add-<project_id_hash>-ue.a.run.app.

Créer une fonction distante

BigQuery utilise une connexion CLOUD_RESOURCE pour interagir avec votre fonction Cloud Run. Pour créer une fonction distante, vous devez créer une connexion CLOUD_RESOURCE. Si vous créez une fonction distante à l'aide de BigQuery DataFrames et que le rôle d'administrateur de projet IAM (roles/resourcemanager.projectIamAdmin) vous a été attribué, vous n'avez pas besoin de créer manuellement la connexion et de lui accorder l'accès. Le service le fait automatiquement.

Créer une connexion

Vous devez disposer d'une connexion à une ressource cloud pour vous connecter à la fonction Cloud Run et à Cloud Run.

Sélectionnez l'une des options suivantes :

Console

  1. Accédez à la page BigQuery.

    Accéder à BigQuery

  2. Pour créer une connexion, cliquez sur Ajouter, puis sur Connexions aux sources de données externes.

  3. Dans la liste Type de connexion, sélectionnez Modèles distants Vertex AI, fonctions distantes et BigLake (ressource Cloud).

  4. Dans le champ ID de connexion, saisissez un nom pour votre connexion.

  5. Cliquez sur Create connection (Créer une connexion).

  6. Cliquez sur Accéder à la connexion.

  7. Dans le volet Informations de connexion, copiez l'ID du compte de service à utiliser à l'étape suivante.

bq

  1. Dans un environnement de ligne de commande, créez une connexion :

    bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID

    Le paramètre --project_id remplace le projet par défaut.

    Remplacez les éléments suivants :

    • REGION : votre région de connexion
    • PROJECT_ID : ID de votre projet Google Cloud
    • CONNECTION_ID : ID de votre connexion

    Lorsque vous créez une ressource de connexion, BigQuery crée un compte de service système unique et l'associe à la connexion.

    Dépannage : Si vous obtenez l'erreur de connexion suivante, mettez à jour le Google Cloud SDK :

    Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...

  2. Récupérez et copiez l'ID du compte de service pour l'utiliser lors d'une prochaine étape :

    bq show --connection PROJECT_ID.REGION.CONNECTION_ID

    Le résultat ressemble à ce qui suit :

    name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

Utilisez la ressource google_bigquery_connection.

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 connexion de ressources Cloud nommée my_cloud_resource_connection dans la région US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

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.

Configurer l'accès

Vous devez accorder à la nouvelle connexion un accès en lecture seule à votre fonction ou service Cloud Run. Il n'est pas recommandé d'autoriser les appels non authentifiés pour votre fonction Cloud Run ou votre service Cloud Run.

Pour attribuer des rôles, procédez comme suit :

  1. Accédez à la page IAM et administration.

    Accéder à IAM et administration

  2. Cliquez sur Ajouter.

    La boîte de dialogue Ajouter des comptes principaux s'ouvre.

  3. Dans le champ Nouveaux comptes principaux, saisissez l'ID du compte de service que vous avez copié précédemment.

  4. Dans le champ Sélectionner un rôle, choisissez l'une des options suivantes :

    • Si vous utilisez une fonction Cloud Run de 1re génération, sélectionnez Fonction Cloud, puis Rôle Demandeur fonction Cloud.
    • Si vous utilisez une fonction Cloud Run de 2e génération, sélectionnez Cloud Run, puis Rôle Demandeur Cloud Run.
    • Si vous utilisez un service Cloud Run, choisissez Cloud Run, puis Rôle Demandeur Cloud Run.

  5. Cliquez sur Enregistrer.

Créer une fonction distante

Pour créer une fonction distante, procédez comme suit :

SQL

Exécutez l'instruction CREATE FUNCTION suivante dans BigQuery :

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

    Accéder à BigQuery

  2. Dans l'éditeur de requête, saisissez l'instruction suivante :

    CREATE FUNCTION PROJECT_ID.DATASET_ID.remote_add(x INT64, y INT64) RETURNS INT64
REMOTE WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
OPTIONS (
  endpoint = 'ENDPOINT_URL'
)

    Remplacez les éléments suivants :

    • DATASET_ID : ID de votre ensemble de données BigQuery.
    • ENDPOINT_URL: URL de votre fonction Cloud Run ou du point de terminaison de fonction distante Cloud Run.

  3. Cliquez sur Exécuter.

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

BigQuery DataFrames

  1. Activez les API requises et assurez-vous de disposer des rôles requis, comme décrit dans la section Conditions requises de la page Fonctions distantes.

  2. Utilisez le décorateur remote_function :

    import bigframes.pandas as bpd

# Set BigQuery DataFrames options
bpd.options.bigquery.project = your_gcp_project_id
bpd.options.bigquery.location = "us"

# BigQuery DataFrames gives you the ability to turn your custom scalar
# functions into a BigQuery remote function. It requires the GCP project to
# be set up appropriately and the user having sufficient privileges to use
# them. One can find more details about the usage and the requirements via
# `help` command.
help(bpd.remote_function)

# Read a table and inspect the column of interest.
df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
df["body_mass_g"].head(10)

# Define a custom function, and specify the intent to turn it into a remote
# function. It requires a BigQuery connection. If the connection is not
# already created, BigQuery DataFrames will attempt to create one assuming
# the necessary APIs and IAM permissions are setup in the project. In our
# examples we will be letting the default connection `bigframes-default-connection`
# be used. We will also set `reuse=False` to make sure we don't
# step over someone else creating remote function in the same project from
# the exact same source code at the same time. Let's try a `pandas`-like use
# case in which we want to apply a user defined scalar function to every
# value in a `Series`, more specifically bucketize the `body_mass_g` value
# of the penguins, which is a real number, into a category, which is a
# string.
@bpd.remote_function(
    float,
    str,
    reuse=False,
)
def get_bucket(num: float) -> str:
    if not num:
        return "NA"
    boundary = 4000
    return "at_or_above_4000" if num >= boundary else "below_4000"

# Then we can apply the remote function on the `Series`` of interest via
# `apply` API and store the result in a new column in the DataFrame.
df = df.assign(body_mass_bucket=df["body_mass_g"].apply(get_bucket))

# This will add a new column `body_mass_bucket` in the DataFrame. You can
# preview the original value and the bucketized value side by side.
df[["body_mass_g", "body_mass_bucket"]].head(10)

# The above operation was possible by doing all the computation on the
# cloud. For that, there is a google cloud function deployed by serializing
# the user code, and a BigQuery remote function created to call the cloud
# function via the latter's http endpoint on the data in the DataFrame.

# The BigQuery remote function created to support the BigQuery DataFrames
# remote function can be located via a property `bigframes_remote_function`
# set in the remote function object.
print(f"Created BQ remote function: {get_bucket.bigframes_remote_function}")

# The cloud function can be located via another property
# `bigframes_cloud_function` set in the remote function object.
print(f"Created cloud function: {get_bucket.bigframes_cloud_function}")

# Warning: The deployed cloud function may be visible to other users with
# sufficient privilege in the project, so the user should be careful about
# having any sensitive data in the code that will be deployed as a remote
# function.

# Let's continue trying other potential use cases of remote functions. Let's
# say we consider the `species`, `island` and `sex` of the penguins
# sensitive information and want to redact that by replacing with their hash
# code instead. Let's define another scalar custom function and decorate it
# as a remote function. The custom function in this example has external
# package dependency, which can be specified via `packages` parameter.
@bpd.remote_function(
    str,
    str,
    reuse=False,
    packages=["cryptography"],
)
def get_hash(input: str) -> str:
    from cryptography.fernet import Fernet

    # handle missing value
    if input is None:
        input = ""

    key = Fernet.generate_key()
    f = Fernet(key)
    return f.encrypt(input.encode()).decode()

# We can use this remote function in another `pandas`-like API `map` that
# can be applied on a DataFrame
df_redacted = df[["species", "island", "sex"]].map(get_hash)
df_redacted.head(10)

Vous devez disposer de l'autorisation bigquery.routines.create sur l'ensemble de données dans lequel vous créez la fonction distante, ainsi que de l'autorisation bigquery.connections.delegate (disponible via le rôle Administrateur de connexion BigQuery) sur la connexion utilisée par la fonction distante.

Fournir un contexte défini par l'utilisateur

Vous pouvez spécifier user_defined_context dans OPTIONS sous la forme de paires clé-valeur, qui feront partie de chaque requête HTTP adressée au point de terminaison. Grâce au contexte défini par l'utilisateur, vous pouvez créer plusieurs fonctions distantes en réutilisant un point de terminaison unique qui se comporte différemment en fonction du contexte qui lui est transmis.

Les exemples suivants créent deux fonctions distantes qui utilisent le même point de terminaison pour chiffrer et déchiffrer les données BYTES.

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.encrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
  endpoint = 'ENDPOINT_URL',
  user_defined_context = [("mode", "encryption")]
)

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.decrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
  endpoint = 'ENDPOINT_URL',
  user_defined_context = [("mode", "decryption")]
)

Limiter le nombre de lignes dans une requête par lot

Vous pouvez spécifier max_batching_rows dans OPTIONS comme nombre maximal de lignes dans chaque requête HTTP, afin d'éviter de dépasser le délai d'expiration des fonctions Cloud Run. Si cette valeur n'est pas spécifiée, BigQuery décide du nombre de lignes incluses dans chaque lot.

Utiliser une fonction distante dans une requête

Assurez-vous d'avoir accordé l'autorisation sur votre fonction Cloud Run, afin qu'elle soit accessible au compte de service BigQuery associé à la connexion de la fonction distante.

Vous devez également disposer de l'autorisationbigquery.routines.get sur l'ensemble de données où se trouve la fonction distante et de l'autorisation bigquery.connections.use que vous pouvez obtenir via le rôle BigQuery Connection User sur la connexion utilisée par la fonction distante.

Vous pouvez utiliser une fonction distante dans une requête de la même façon qu'une fonction définie par l'utilisateur.

Par exemple, vous pouvez utiliser la fonction remote_add dans l'exemple de requête :

SELECT
  val,
  `PROJECT_ID.DATASET_ID`.remote_add(val, 2)
FROM
  UNNEST([NULL,2,3,5,8]) AS val;

Cet exemple génère la sortie suivante :

+------+-----+
|  val | f0_ |
+------+-----+
| NULL |   2 |
|    2 |   4 |
|    3 |   5 |
|    5 |   7 |
|    8 |  10 |
+------+-----+

Régions où le service est disponible

Il existe deux types de zones dans BigQuery :

  • Une région est un emplacement géographique spécifique, par exemple Londres.

  • Une zone multirégionale correspond à un secteur géographique de grande étendue, par exemple les États-Unis, et comporte au moins deux lieux géographiques.

Régions uniques

Dans un ensemble de données BigQuery régional unique, vous ne pouvez créer qu'une fonction distante utilisant une fonction Cloud Run déployée dans la même région. Exemple :

  • Une fonction distante dans BigQuery région unique us-east4 ne peut utiliser qu'une fonction Cloud Run dans us-east4.

Ainsi, pour les régions uniques, les fonctions distantes ne sont disponibles que dans les régions compatibles à la fois avec Cloud Run et BigQuery.

Emplacements multirégionaux

Dans un ensemble de données BigQuery multirégional (US, EU), vous ne pouvez créer une fonction distante que si elle utilise une fonction Cloud Run déployée dans une région située dans la même zone géographique (États-Unis, UE). Exemple :

  • Une fonction distante dans la zone multirégionale BigQuery US ne peut utiliser qu'une fonction Cloud Run déployée dans une région unique de la zone géographique des États-Unis, par exemple us-central1, us-east4, us-west2, etc.
  • Une fonction distante dans la zone multirégionale BigQuery EU ne peut utiliser qu'une fonction Cloud Run déployée dans une région unique des États membres de l'Union européenne, telle que europe-north1, europe-west3, etc.

Pour en savoir plus sur les régions et les zones multirégionales BigQuery, consultez la page Emplacements des ensembles de données. Pour en savoir plus sur les régions des fonctions Cloud Run, consultez la page Emplacements des fonctions Cloud Run.

Connexions

Pour une zone régionale ou multirégionale, vous ne pouvez créer une fonction distante que dans la zone utilisée pour la connexion. Par exemple, pour créer une fonction distante dans la zone multirégionale US, utilisez une connexion située dans la zone multirégionale US.

Tarifs

Utiliser VPC Service Controls

VPC Service Controls est une fonctionnalité de Google Cloud qui vous permet de configurer un périmètre sécurisé pour vous protéger contre l'exfiltration de données. Pour utiliser VPC Service Controls avec des fonctions distantes afin de renforcer la sécurité, ou pour utiliser des points de terminaison avec les paramètres d'entrée internal traffic, suivez le guide VPC Service Controls pour effectuer les opérations suivantes :

  1. Créer un périmètre de service

  2. Ajouter le projet BigQuery de la requête en utilisant la fonction distante dans le périmètre.

  3. Ajouter le projet de point de terminaison au périmètre et définir Cloud Functions API ou Cloud Run API dans les services restreints en fonction du type de point de terminaison. Pour en savoir plus, consultez les pages VPC Service Controls dans les fonctions Cloud Run et VPC Service Controls dans Cloud Run.

Bonnes pratiques pour les fonctions distantes

  • Préfiltrer votre entrée : si votre entrée peut facilement être filtrée avant d'être transmise à une fonction distante, la requête sera probablement plus rapide et plus économique.

  • Assurez le scaling de votre fonction Cloud Run. Le scaling est une fonction du nombre minimal d'instances, du nombre maximal d'instances et de la simultanéité.

    • Dans la mesure du possible, utilisez la valeur par défaut pour le nombre maximal d'instances de votre fonction Cloud Run.
    • Notez qu'il n'existe pas de limite par défaut pour les fonctions Cloud Run HTTP de 1re génération. Pour éviter les événements de scaling illimité avec les fonctions Cloud Run HTTP de 1re génération lors des tests ou en production, nous vous recommandons de définir une limite, par exemple 3 000.

  • Suivez d'autres conseils sur les fonctions Cloud Run pour améliorer les performances. Les requêtes de fonction distante interagissant avec une fonction Cloud Run à latence élevée peuvent échouer en raison du délai avant expiration.

  • Implémentez votre point de terminaison pour renvoyer un code de réponse HTTP et une charge utile appropriés en cas d'échec de réponse.

    • Pour réduire les tentatives de BigQuery, utilisez des codes de réponse HTTP autres que 408, 429, 500, 503 et 504 en cas d'échec de réponse, et veillez à intercepter toutes les exceptions dans votre code de fonction. Sinon, le framework de service HTTP peut renvoyer automatiquement un code 500 pour toute exception non détectée. Il se peut que des requêtes HTTP relancées s'affichent toujours lorsque BigQuery relance une partition de données ou une requête ayant échoué.

    • Votre point de terminaison doit renvoyer une charge utile JSON au format défini lors d'un échec de réponse. Même si ce n'est pas strictement obligatoire, il aide BigQuery à déterminer si la réponse ayant échoué est issue de la mise en œuvre de votre fonction ou de l'infrastructure de Cloud Run Functions/Cloud Run. Pour ce dernier cas, BigQuery peut réessayer avec une limite interne différente.

Quotas

Pour en savoir plus sur les quotas des fonctions distantes, consultez la page Quotas et limites.