Utilizzare le funzioni remote

Una funzione remota BigQuery ti consente di implementare la tua funzione in altre lingue 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 BigQuery ti consente di incorporare la funzionalità GoogleSQL con software esterni a BigQuery fornendo un'integrazione diretta con Cloud Run Functions e Cloud Run. Con le funzioni remote di BigQuery, puoi eseguire il deployment delle funzioni in Cloud Run Functions o Cloud Run implementato 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 restituito:

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

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

• Non puoi creare funzioni remote con valori di tabella.

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

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

• Potresti visualizzare richieste ripetute con gli stessi dati al tuo 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 ignorata per alcune righe a causa di un cortocircuito, ad esempio in espressioni condizionali o in un'istruzione MERGE con WHEN [NOT] MATCHED, il batching non viene utilizzato con la funzione remota. In questo caso, il campo calls nel corpo della richiesta HTTP contiene 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 interrogata 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 HTTP POST e restituire i risultati del batch come risposta HTTP.

Se crei la funzione remota utilizzando BigQuery DataFrames, non devi creare manualmente l'endpoint HTTP. Il servizio lo fa automaticamente per te.

Consulta il tutorial su Cloud Run Functions e altra documentazione di Cloud Run Functions 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 tua funzione Cloud Run o del tuo servizio Cloud Run.

Formato di input

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

Esempio di richiesta:

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

Formato di output

BigQuery prevede 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.

Esempio di risposta corretta:

{
  "replies": [
    1,
    0
  ]
}

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 riuscita. Quando BigQuery riceve qualsiasi altro valore, BigQuery considera la risposta come un errore e riprova quando il codice di risposta HTTP è 408, 429, 500, 503 o 504 fino a un limite interno.

Codifica JSON del tipo di dati SQL

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

Codice di esempio della funzione Cloud Run

Il seguente esempio di codice Python implementa l'aggiunta di tutti gli argomenti interi della funzione remota. Gestisce una richiesta con gli argomenti per le chiamate batch e restituisce tutti i risultati 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 implementata nel progetto my_gcf_project nella regione us-east1 con il nome remote_add, è possibile accedervi tramite l'endpoint https://us-east1-my_gcf_project.cloudfunctions.net/remote_add.

Codice 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 creare ed eseguire il deployment del codice.

Supponendo che il servizio Cloud Run venga eseguito il deployment 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 tua funzione Cloud Run. Per creare una funzione remota, devi creare una connessione CLOUD_RESOURCE. Se crei la funzione remota utilizzando BigQuery DataFrames e ti è stato concesso il ruolo Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin), non devi creare manualmente la connessione e concederne 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 a una risorsa Cloud.

Puoi saltare questo passaggio se hai configurato una connessione predefinita o se disponi del ruolo Amministratore BigQuery.

Crea una connessione a una risorsa Cloud da utilizzare per il modello remoto e recupera il account di servizio della connessione. Crea la connessione nella stessa posizione del set di dati che hai creato nel passaggio precedente.

Seleziona una delle seguenti opzioni:

# 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 {}
}

Configura l'accesso

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

Per concedere i ruoli, segui questi passaggi:

1. Vai alla pagina IAM e amministrazione.

   Vai a IAM e amministrazione

2. Fai clic su person_add Aggiungi.

   Si apre 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 prima generazione, scegli funzione Cloud Functions e poi seleziona Ruolo Invoker di Cloud Functions.
   • Se utilizzi una funzione Cloud Run di seconda 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 invoker Cloud Run.

5. Fai clic su Salva.

Creare una funzione remota

Per creare una funzione remota:

Devi disporre dell'autorizzazione bigquery.routines.create sul set di dati in cui crei la funzione remota e dell'autorizzazione bigquery.connections.delegate (disponibile dal 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 che gli viene trasmesso.

Gli esempi seguenti 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 specifichi max_batching_rows, BigQuery determina il numero di righe in un batch fino al limite di max_batching_rows. Se non specificato, BigQuery determina automaticamente il numero di righe da raggruppare.

Utilizzare una funzione remota in una query

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

Devi anche disporre dell'autorizzazione bigquery.routines.get sul 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, sulla connessione utilizzata dalla funzione remota.

Puoi utilizzare una funzione remota in una query proprio come 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

Esistono due tipi di località in BigQuery:

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

• Una località a più regioni è una realtà geografica di grandi dimensioni, come gli Stati Uniti, che contiene due o più luoghi geografici.

Regioni singole

In un set di dati BigQuery a 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 in BigQuery in una singola regione 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 Cloud Run Functions che BigQuery.

Più regioni

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

• Una funzione remota nella regione BigQuery US multi-region può utilizzare solo una funzione Cloud Run di cui è stato eseguito il deployment in una singola regione nell'area geografica degli Stati Uniti, ad esempio us-central1, us-east4, us-west2 e così via.
• Una funzione remota nella regione multiregionale EU di BigQuery 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 sulle multiregioni 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à a una sola regione o a più regioni, puoi creare una funzione remota solo nella stessa località della connessione che utilizzi. Ad esempio, per creare una funzione remota nella multiregione US, utilizza una connessione che si trova nella multiregione US.

Prezzi

• Vengono applicati i prezzi standard di BigQuery.

• Inoltre, l'utilizzo di questa funzionalità potrebbe comportare costi per le funzioni Cloud Run e Cloud Run. Per maggiori dettagli, consulta le pagine dei prezzi di Cloud Run Functions e Cloud Run.

Utilizzo dei Controlli di servizio VPC

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

1. Crea un perimetro di servizio.

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

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 ulteriori dettagli, consulta Controlli di servizio VPC per Cloud Run Functions 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ù veloce ed economica.

• Mantieni la scalabilità della tua 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 di Cloud Run Functions.
  • Tieni presente che non esiste un limite predefinito per le funzioni Cloud Run HTTP di 1ª generazione. Per evitare eventi di scalabilità illimitata con le funzioni Cloud Run HTTP di 1ª generazione durante il test o in produzione, ti consigliamo di impostare un limite, ad esempio 3000.

• Segui altri suggerimenti per le funzioni Cloud Run per prestazioni migliori. Le query di funzioni remote che interagiscono con una funzione Cloud Run a latenza elevata potrebbero non riuscire a causa del timeout.

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

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

  • L'endpoint deve restituire un payload JSON nel formato definito per una risposta non riuscita. Anche se non è strettamente necessario, aiuta BigQuery a distinguere se la risposta non riuscita proviene dall'implementazione della funzione o dall'infrastruttura di Cloud Run Functions/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.