Lavorare con le funzioni remote

Una funzione remota BigQuery ti consente di implementare la tua funzione in altri linguaggi oltre a SQL e JavaScript o con le librerie o i servizi non consentiti nelle funzioni definite dall'utente di BigQuery.

Panoramica

Una funzione remota di BigQuery ti consente di incorporare la funzionalità GoogleSQL con software esterno a BigQuery, fornendo un'integrazione diretta con le funzioni Cloud Run e Cloud Run. Con le funzioni remote di BigQuery, puoi eseguire il deployment delle funzioni in Cloud Functions o Cloud Run implementate con qualsiasi linguaggio supportato e poi richiamarle dalle query GoogleSQL.

Flusso di lavoro

  1. Crea l'endpoint HTTP nelle funzioni Cloud Run o in Cloud Run.
  2. Crea una funzione remota in BigQuery.
    1. Crea una connessione di tipo CLOUD_RESOURCE.
    2. Crea una funzione remota.
  3. Utilizza la funzione remota in una query come qualsiasi altra funzione definita dall'utente.

Limitazioni

  • Le funzioni remote supportano solo uno dei seguenti tipi di dati come tipo di argomento o tipo di ritorno:

    • Booleano
    • Byte
    • Numerico
    • Stringa
    • Data
    • Data/ora
    • Ora
    • Timestamp
    • JSON

    Le funzioni remote non supportano i tipi ARRAY, STRUCT, INTERVAL o GEOGRAPHY.

  • Non puoi creare funzioni remote temporanee.

  • Non puoi creare funzioni remote con valori di tabella.

  • Non puoi utilizzare le funzioni remote durante la creazione delle viste materializzate.

  • Si presume sempre che il valore restituito di una funzione remota sia non deterministico, pertanto il risultato di una query che chiama una funzione remota non viene memorizzato nella cache.

  • Potresti notare richieste ripetute con gli stessi dati all'endpoint, anche dopo risposte positive, a causa di errori di rete temporanei o errori interni di BigQuery.

  • Quando la valutazione di una funzione remota viene saltata per alcune righe a causa di un cortocircuito, ad esempio nelle espressioni condizionali o in un istruzione MERGE con WHEN [NOT] MATCHED, il raggruppamento non viene utilizzato con la funzione remota. In questo caso, il campo calls nel corpo della richiesta HTTP ha esattamente un elemento.

  • Se il set di dati associato alla funzione remota viene replicato in una regione di destinazione tramite la replica dei set di dati tra regioni, la funzione remota può essere sottoposta a query solo nella regione in cui è stata creata.

Creazione di un endpoint

Per creare una funzione remota che possa implementare la logica di business, devi creare un endpoint HTTP utilizzando le funzioni Cloud Run o Cloud Run. L'endpoint deve essere in grado di elaborare un batch di righe in una singola richiesta POST HTTP e restituire i risultati del batch come risposta HTTP.

Se crei la funzione remota utilizzando DataFrame di BigQuery, non devi creare manualmente l'endpoint HTTP; il servizio lo fa automaticamente per te.

Consulta il tutorial sulle funzioni Cloud Run e altra documentazione sulle funzioni Cloud Run su come scrivere, eseguire il deployment, testare e gestire una funzione Cloud Run.

Consulta la guida rapida di Cloud Run e altra documentazione di Cloud Run su come scrivere, eseguire il deployment, testare e gestire un servizio Cloud Run.

Ti consigliamo di mantenere l'autenticazione predefinita anziché consentire la chiamata non autenticata della funzione o del servizio Cloud Run.

Formato di input

BigQuery invia richieste POST HTTP con corpo JSON nel seguente formato:

Nome campo Descrizione Tipo di campo
requestId ID della richiesta. Univoco per più richieste inviate a questo endpoint in una query GoogleSQL. Fornito sempre. Stringa.
chiamante Nome completo della risorsa job per la query GoogleSQL che chiama la funzione remota. Fornito sempre. Stringa.
sessionUser Indirizzo email dell'utente che esegue la query GoogleSQL. Fornito sempre. Stringa.
userDefinedContext Il contesto definito dall'utente utilizzato per creare la funzione remota in BigQuery. Facoltativo. Un oggetto JSON con coppie chiave-valore.
chiamate Un batch di dati di input. Fornito sempre. Un array JSON.

Ogni elemento è un array JSON, ovvero un elenco di argomenti codificati in JSON di una chiamata di funzione remota.

Esempio di richiesta:

{
 "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]
 ]
}

Formato di output

BigQuery si aspetta che l'endpoint restituisca una risposta HTTP nel seguente formato, altrimenti BigQuery non può utilizzarla e la query che chiama la funzione remota non andrà a buon fine.

Nome campo Descrizione Intervallo di valori
risposte Un batch di valori restituiti. Obbligatorio per una risposta corretta. Un array JSON.

Ogni elemento corrisponde a un valore restituito codificato in JSON della funzione esterna.

Le dimensioni dell'array devono corrispondere a quelle dell'array JSON di calls nella richiesta HTTP. Ad esempio, se l'array JSON in calls ha 4 elementi, anche questo array JSON deve avere 4 elementi.

errorMessage Messaggio di errore quando viene restituito un codice di risposta HTTP diverso da 200. Per gli errori non ripetibili, lo restituiamo all'utente come parte del messaggio di errore del job BigQuery. Facoltativo. Stringa. La dimensione deve essere inferiore a 1 KB.

Un esempio di risposta corretta:

{
  "replies": [
    1,
    0
  ]
}

Un esempio di risposta non riuscita:

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

Codice di risposta HTTP

L'endpoint deve restituire il codice di risposta HTTP 200 per una risposta positiva. Quando BigQuery riceve un altro valore, considera la risposta come un errore e riprova quando il codice di risposta HTTP è 408, 429, 500, 503 o 504 fino a un determinato limite interno.

Codifica JSON del tipo di dati SQL

La codifica JSON nella richiesta/risposta HTTP segue la codifica JSON esistente di BigQuery per la funzione TO_JSON_STRING.

Codice di esempio della funzione Cloud Run

Il seguente codice di esempio Python implementa l'aggiunta di tutti gli argomenti interi della funzione remota. Gestisce una richiesta con gli argomenti per le invocazioni collettive e restituisce tutto il risultato in una risposta.

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

Supponendo che la funzione sia dipiattata nel progetto my_gcf_project nella regione us-east1 come nome funzione remote_add, è possibile accedervi tramite l'endpoint https://us-east1-my_gcf_project.cloudfunctions.net/remote_add.

Codice di Cloud Run di esempio

Il seguente codice Python di esempio implementa un servizio web, che può essere creato e distribuito in Cloud Run per la stessa funzionalità.

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

Consulta la guida su come compilare ed eseguire il deployment del codice.

Supponendo che il servizio Cloud Run sia dipiegato nel progetto my_gcf_project nella regione us-east1 con il nome del servizio remote_add, è possibile accedervi tramite l'endpoint https://remote_add-<project_id_hash>-ue.a.run.app.

Creare una funzione remota

BigQuery utilizza una connessione CLOUD_RESOURCE per interagire con la funzione Cloud Run. Per creare una funzione remota, devi creare una connessione CLOUD_RESOURCE. Se crei la funzione remota utilizzando DataFrame di BigQuery e ti è stato concesso il ruolo Amministratore IAM del progetto (roles/resourcemanager.projectIamAdmin), non devi creare manualmente la connessione e concederle l'accesso. Il servizio lo fa automaticamente per te.

Crea una connessione

Per connetterti alla funzione Cloud Run e a Cloud Run, devi disporre di una connessione alla risorsa Cloud.

Seleziona una delle seguenti opzioni:

Console

  1. Vai alla pagina BigQuery.

    Vai a BigQuery

  2. Per creare una connessione, fai clic su Aggiungi e poi su Connessioni a origini dati esterne.

  3. Nell'elenco Tipo di connessione, seleziona Modelli remoti di Vertex AI, funzioni remote e BigLake (risorsa Cloud).

  4. Nel campo ID connessione, inserisci un nome per la connessione.

  5. Fai clic su Crea connessione.

  6. Fai clic su Vai alla connessione.

  7. Nel riquadro Informazioni sulla connessione, copia l'ID account di servizio da utilizzare in un passaggio successivo.

bq

  1. In un ambiente a riga di comando, crea una connessione:

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

    Il parametro --project_id sostituisce il progetto predefinito.

    Sostituisci quanto segue:

    • REGION: la regione di connessione
    • PROJECT_ID: il tuo ID progetto Google Cloud
    • CONNECTION_ID: un ID per la connessione

    Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema unico e lo associa alla connessione.

    Risoluzione dei problemi: se ricevi il seguente errore di connessione, aggiorna Google Cloud SDK:

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

  2. Recupera e copia l'ID account di servizio per utilizzarlo in un passaggio successivo:

    bq show --connection PROJECT_ID.REGION.CONNECTION_ID

    L'output è simile al seguente:

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

Terraform

Utilizza la risorsa google_bigquery_connection.

Per autenticarti in BigQuery, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

L'esempio seguente crea una connessione risorsa Cloud denominata my_cloud_resource_connection nella regione 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 {}
}

Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle seguenti sezioni.

Prepara Cloud Shell

  1. Avvia Cloud Shell.

  2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

    Devi eseguire questo comando una sola volta per progetto e puoi farlo in qualsiasi directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione di Terraform deve avere una propria directory (chiamata anche modulo principale).

  1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel main.tf appena creato.

    Se vuoi, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory. 
    terraform init

    Se vuoi, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade: 

    terraform init -upgrade

Applica le modifiche

  1. Rivedi la configurazione e verifica che le risorse che Terraform sta per creare o aggiornare corrispondano alle tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

  2. Applica la configurazione di Terraform eseguendo il seguente comando e inserendo yes al prompt: 
    terraform apply

    Attendi che Terraform mostri il messaggio "Applicazione completata".

  3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Configurare l'accesso

Devi concedere alla nuova connessione l'accesso in sola lettura alla funzione o al servizio Cloud Run. Non è consigliabile consentire l'invocazione non autenticata per la funzione o il servizio Cloud Run.

Per concedere i ruoli:

  1. Vai alla pagina IAM e amministrazione.

    Vai a IAM e amministrazione

  2. Fai clic su Aggiungi.

    Viene visualizzata la finestra di dialogo Aggiungi entità.

  3. Nel campo Nuove entità, inserisci l'ID account di servizio che hai copiato in precedenza.

  4. Nel campo Seleziona un ruolo, seleziona una delle seguenti opzioni:

    • Se utilizzi una funzione Cloud Run di 1ª generazione, scegli funzione Cloud Functions e poi seleziona Ruolo Invoker della funzione Cloud Functions.
    • Se utilizzi una funzione Cloud Run di 2ª generazione, scegli Cloud Run e poi seleziona Ruolo Invoker di Cloud Run.
    • Se utilizzi un servizio Cloud Run, scegli Cloud Run e poi seleziona Ruolo invocatore Cloud Run.

  5. Fai clic su Salva.

Creare una funzione remota

Per creare una funzione remota:

SQL

Esegui la seguente CREATE FUNCTION istruzione in BigQuery:

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

    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'
)

    Sostituisci quanto segue:

    • DATASET_ID: l'ID del set di dati BigQuery.
    • ENDPOINT_URL: l'URL della funzione Cloud Run o dell'endpoint della funzione remota Cloud Run.

  3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

BigQuery DataFrames

  1. Attiva le API richieste e assicurati di aver ricevuto i ruoli necessari, come descritto nella sezione Requisiti di Funzioni remote.

  2. Utilizza il decoratore 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)

Devi disporre dell'autorizzazione bigquery.routines.create sul set di dati in cui crei la funzione remota e dell'autorizzazione bigquery.connections.delegate (disponibile nel ruolo Amministratore connessione BigQuery) sulla connessione utilizzata dalla funzione remota.

Fornire un contesto definito dall'utente

Puoi specificare user_defined_context in OPTIONS come forma di coppie chiave-valore, che faranno parte di ogni richiesta HTTP all'endpoint. Con il contesto definito dall'utente, puoi creare più funzioni remote, ma riutilizzare un singolo endpoint che fornisce comportamenti diversi in base al contesto a cui viene passato.

I seguenti esempi creano due funzioni remote per criptare e decriptare i dati BYTES utilizzando lo stesso endpoint.

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")]
)

Limitare il numero di righe in una richiesta batch

Puoi specificare max_batching_rows in OPTIONS come numero massimo di righe in ogni richiesta HTTP, per evitare il timeout delle funzioni Cloud Run. Se non viene specificato, BigQuery decide quante righe sono incluse in un batch.

Utilizzare una funzione remota in una query

Assicurati di avere concesso l'autorizzazione alla funzione Cloud Run, in modo che sia accessibile all'account di servizio di BigQuery associato alla connessione della funzione remota.

Devi disporre anche dell'autorizzazione bigquery.routines.get per il set di dati in cui si trova la funzione remota e dell'autorizzazione bigquery.connections.use, che puoi ottenere tramite il ruolo BigQuery Connection User, per la connessione utilizzata dalla funzione remota.

Puoi utilizzare una funzione remota in una query come faresti con una funzione definita dall'utente.

Ad esempio, puoi utilizzare la funzione remote_add nella query di esempio:

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

Questo esempio produce il seguente output:

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

Aree geografiche supportate

In BigQuery esistono due tipi di località:

  • Una regione è un luogo geografico ben preciso, come Londra.

  • Per più regioni si intende una vasta area geografica, come gli Stati Uniti, che contiene due o più luoghi geografici.

Regioni singole

In un set di dati BigQuery di una singola regione, puoi creare solo una funzione remota che utilizza una funzione Cloud Run di cui è stato eseguito il deployment nella stessa regione. Ad esempio:

  • Una funzione remota nella singola regione BigQuery us-east4 può utilizzare solo una funzione Cloud Run in us-east4.

Pertanto, per le singole regioni, le funzioni remote sono supportate solo nelle regioni che supportano sia le funzioni Cloud Run sia BigQuery.

Più regioni

In un set di dati BigQuery multi-regione (US, EU), puoi solo creare una funzione remota che utilizza una funzione Cloud Run di cui è stato eseguito il deployment in una regione all'interno della stessa vasta area geografica (US, UE). Ad esempio:

  • Una funzione remota in BigQuery US multi-regione può utilizzare solo una funzione Cloud Run di cui è stato eseguito il deployment in una singola regione dell'area geografica degli Stati Uniti, come us-central1, us-east4, us-west2 e così via.
  • Una funzione remota in BigQuery EU multi-regione può utilizzare solo una funzione Cloud Run di cui è stato eseguito il deployment in una singola regione degli stati membri dell'Unione Europea, ad esempio europe-north1, europe-west3 e così via.

Per saperne di più sulle regioni e sui multiregioni di BigQuery, consulta la pagina Località dei set di dati. Per ulteriori informazioni sulle regioni di Cloud Run Functions, consulta la pagina Località di Cloud Run Functions.

Connessioni

Per una località in una singola regione o in più regioni, puoi creare una funzione remota solo nella stessa località della connessione utilizzata. Ad esempio, per creare una funzione remota nella regione multipla US, utilizza una connessione situata nella regione multipla US.

Prezzi

Utilizzo dei Controlli di servizio VPC

Controlli di servizio VPC è una funzionalità di Google Cloud che ti consente di configurare un perimetro sicuro per proteggerti dall'esfiltrazione di dati. Per utilizzare Controlli di servizio VPC con funzioni remote per una maggiore sicurezza o per utilizzare endpoint con internal traffic impostazioni di ingresso, segui la guida ai Controlli di servizio VPC per:

  1. Crea un perimetro di servizio.

  2. Aggiungi il progetto BigQuery della query che utilizza la funzione remota al perimetro.

  3. Aggiungi il progetto dell'endpoint al perimetro e imposta Cloud Functions API o Cloud Run API nei servizi limitati in base al tipo di endpoint. Per maggiori dettagli, consulta Controlli di servizio VPC per le funzioni Cloud Run e Controlli di servizio VPC per Cloud Run.

Best practice per le funzioni remote

  • Prefiltra l'input: se l'input può essere facilmente filtrato prima di essere passato a una funzione remota, la query sarà probabilmente più rapida ed economica.

  • Mantieni scalabile la funzione Cloud Run. La scalabilità è una funzione di istanze minime, istanze massime e concorrenza.

    • Se possibile, utilizza il valore predefinito per il numero massimo di istanze della funzione Cloud Run.
    • Tieni presente che non esiste un limite predefinito per le funzioni Cloud Run HTTP di 1ª generazione. Per evitare eventi di scalabilità illimitati con le funzioni Cloud Run HTTP di 1ª generazione. durante i test o in produzione, ti consigliamo di impostare un limite, ad esempio 3000.

  • Segui altri suggerimenti per le funzioni Cloud Run per migliorare il rendimento. Le query delle funzioni remote che interagiscono con una funzione Cloud Run ad alta latenza potrebbero non riuscire a causa di un timeout.

  • Implementa l'endpoint in modo da restituire un codice di risposta HTTP e un payload corretti per una risposta non riuscita.

    • Per ridurre al minimo i tentativi da BigQuery, utilizza codici di risposta HTTP diversi da 408, 429, 500, 503 e 504 per una risposta non riuscita e assicurati di gestire tutte le eccezioni nel codice della funzione. In caso contrario, il framework del servizio HTTP potrebbe restituire automaticamente 500 per eventuali eccezioni non rilevate. Potresti comunque visualizzare richieste HTTP riprovate quando BigQuery riprova una query o una partizione di dati non riuscita.

    • L'endpoint deve restituire un payload JSON nel formato definito per una risposta con errore. Anche se non è strettamente necessario, aiuta BigQuery a distinguere se la risposta non riuscita proviene dall'implementazione della funzione o dall'infrastruttura delle funzioni Cloud Run/Cloud Run. Per quest'ultimo, BigQuery potrebbe riprovare con un limite interno diverso.

Quote

Per informazioni sulle quote delle funzioni remote, consulta Quote e limiti.