Utilizza le funzioni remote

Puoi utilizzare le funzioni remote di BigQuery per implementare funzioni personalizzate utilizzando linguaggi, librerie o servizi non supportati dalle funzioni definite dall'utente standard. Puoi eseguire il deployment delle funzioni remote in Cloud Run o Cloud Run Functions per richiamarle direttamente dalle query GoogleSQL.

Workflow

  1. Crea l'endpoint HTTP in Cloud Run Functions o 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 remote non supportano i tipi ARRAY, STRUCT, INTERVAL o GEOGRAPHY.

  • Non puoi creare funzioni remote con valori di tabella.

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

  • Il valore restituito di una funzione remota viene sempre considerato non deterministico, pertanto 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 riuscite, 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 batching 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, è possibile eseguire query sulla funzione remota solo nella regione in cui è stata creata.

  • Le funzioni remote supportano un percorso personalizzato nell'URL dell'endpoint. I percorsi personalizzati presentano le seguenti limitazioni:

    • Nel percorso sono consentiti solo lettere maiuscole (A-Z), lettere minuscole (a-z), cifre (0-9), trattini (-) e trattini bassi (_).
    • Gli identificatori di frammenti (#), parametri di ricerca (?) e le tildi (~) non sono consentiti.
    • I percorsi che iniziano con /_ah/, il percorso specifico /eventlog e qualsiasi percorso che termina con la lettera z non sono consentiti.

Creazione di un endpoint

Per creare una funzione remota in grado di implementare la logica di business, devi creare un endpoint HTTP utilizzando Cloud Run Functions 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 per il batch come risposta HTTP. Le funzioni remote supportano un percorso personalizzato nell'URL dell'endpoint (vedi le limitazioni).

Se crei la funzione remota utilizzando BigQuery DataFrames, non devi creare manualmente l'endpoint HTTP, perché 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 funzione Cloud Run 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. Sempre fornito. Stringa.
chiamante Nome completo della risorsa del job per la query GoogleSQL che chiama la funzione remota. Sempre fornito. Stringa.
sessionUser Email dell'utente che esegue la query GoogleSQL. Sempre fornito. Stringa.
userDefinedContext Il contesto definito dall'utente utilizzato durante la creazione della funzione remota in BigQuery. Facoltativo. Un oggetto JSON con coppie chiave-valore.
chiamate Un batch di dati di input. Sempre fornito. Un array JSON.

Ogni elemento è a sua volta 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
di 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.

La dimensione dell'array deve corrispondere a quella 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 ritentabili, restituiamo questo valore all'utente come parte del messaggio di errore del job BigQuery. Facoltativo. Stringa. La dimensione deve essere inferiore a 1 kB.

Esempio di risposta corretta:

{
  "replies": [
    1,
    0
  ]
}

Esempio di risposta con esito negativo:

{
  "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 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 limite interno.

Codifica JSON del tipo di dati SQL

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

Codice di esempio di una funzione Cloud Run

Il seguente codice Python di esempio implementa l'aggiunta di tutti gli argomenti interi della funzione remota. Gestisce una richiesta con gli argomenti per le chiamate in 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://docs.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 il deployment della funzione venga eseguito nel progetto my_gcf_project nella regione us-east1 con il nome funzione remote_add, è possibile accedervi utilizzando 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 di cui può essere eseguito il deployment 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://docs.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 deployment del servizio Cloud Run venga eseguito nel progetto my_gcf_project nella regione us-east1 con il nome servizio remote_add, è possibile accedervi utilizzando l'endpoint https://remote_add-<project_id_hash>-ue.a.run.app.

Il seguente esempio Python implementa un percorso di route diverso /subtract_list (consulta le limitazioni del percorso dell'URL personalizzato) nel servizio web di cui è stato eseguito il deployment in precedenza:

@app.route("/subtract_list", methods=['POST'])
def batch_subtract():
  """
  Processes batch requests to subtract numbers within inner lists (e.g., a - b - c).
  Handles integers, string representations of integers, and None values.
  """
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      nums_to_process = [int(x) if isinstance(x, str) else x for x in call if x is not None]
      if not nums_to_process:
        result = 0
      else:
        result = nums_to_process[0] - sum(nums_to_process[1:])
      return_value.append(result)
    replies = [str(x) if abs(x) > _MAX_LOSSLESS else x for x in return_value]
    return jsonify({"replies": replies})
  except Exception as e:
    return jsonify({"errorMessage": str(e)}), 400

Crea 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 concedere l'accesso; il servizio lo fa automaticamente per te.

Crea una connessione

Devi disporre di una connessione alle risorse Cloud per connetterti a Cloud Run Functions e Cloud Run.

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

Seleziona una delle seguenti opzioni:

Console

  1. Vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nel riquadro a sinistra, fai clic su Explorer:

    Pulsante evidenziato per il riquadro Spazio di esplorazione.

    Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

  3. Nel riquadro Explorer, espandi il nome del progetto, quindi fai clic su Connessioni.

  4. Nella pagina Connessioni, fai clic su Crea connessione.

  5. In Tipo di connessione, scegli Modelli remoti di Vertex AI, funzioni remote, BigLake e Spanner (risorsa Cloud).

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

  7. In Tipo di località, seleziona una località per la connessione. La connessione deve essere collocata insieme alle altre risorse, ad esempio i set di dati.

  8. Fai clic su Crea connessione.

  9. Fai clic su Vai alla connessione.

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

SQL

Utilizza l'istruzione CREATE CONNECTION:

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

    Vai a BigQuery

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

    CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
OPTIONS (
  connection_type = "CLOUD_RESOURCE",
  friendly_name = "FRIENDLY_NAME",
  description = "DESCRIPTION"
  );

    Sostituisci quanto segue:

    • CONNECTION_NAME: il nome della connessione nel formato PROJECT_ID.LOCATION.CONNECTION_ID, LOCATION.CONNECTION_ID o CONNECTION_ID. Se il progetto o la località vengono omessi, vengono dedotti dal progetto e dalla località in cui viene eseguita l'istruzione.
    • FRIENDLY_NAME (facoltativo): un nome descrittivo per la connessione.
    • DESCRIPTION (facoltativo): una descrizione della connessione.

  3. Fai clic su Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

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 tua regione di connessione
    • PROJECT_ID: il tuo ID progetto Google Cloud
    • CONNECTION_ID: un ID per la tua connessione

    Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco 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 da utilizzare 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."}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

Utilizza la risorsa google_bigquery_connection.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

L'esempio seguente crea una connessione alle risorse 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 di Terraform in un progetto Google Cloud , completa i passaggi descritti nelle sezioni seguenti.

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 eseguirlo 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 Terraform deve avere la 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 file main.tf appena creato.

    Facoltativamente, 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

    Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade: 

    terraform init -upgrade

Applica le modifiche

  1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

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

    Attendi finché Terraform non visualizza il messaggio "Apply complete!".

  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.

Configura l'accesso

Devi concedere alla nuova connessione l'accesso di 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 Aggiungi.

    Si apre la finestra di dialogo Aggiungi entità.

  3. Nel campo Nuove entità, inserisci l'ID del 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ª gen., scegli Cloud Functions, quindi seleziona Ruolo Cloud Functions Invoker.
    • Se utilizzi una funzione Cloud Run di 2ª gen., scegli Cloud Run, quindi seleziona Ruolo Cloud Run Invoker.
    • Se utilizzi un servizio Cloud Run, scegli Cloud Run, quindi seleziona Ruolo Invoker di Cloud Run.

  5. Fai clic su Salva.

Crea una funzione remota

Per creare una funzione remota:

SQL

Esegui la seguente istruzione CREATE FUNCTION 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: un URL della funzione Cloud Run o dell'endpoint della funzione remota Cloud Run. Le funzioni remote supportano un percorso personalizzato nell'URL dell'endpoint (consulta le limitazioni del percorso personalizzato). È possibile creare funzioni remote diverse su ogni percorso di route nella stessa applicazione. L'opzione endpoint nell'istruzione CREATE FUNCTION può includere un percorso di route immediatamente dopo un URL Cloud Run (ad esempio, https://service_name-project_number.region.run.app/subtract_list).

  3. Fai clic su Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

BigQuery DataFrames

  1. Abilita le API richieste e assicurati che ti siano stati concessi i ruoli richiesti, come descritto nella sezione Requisiti di Funzioni remote.
  2. Utilizza il decoratore remote_function.

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

Limitazione del 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 di Cloud Run Functions. Se specifichi max_batching_rows, BigQuery determina il numero di righe in un batch fino al limite max_batching_rows. Se non specificato, BigQuery determina automaticamente il numero di righe da raggruppare in batch.

Utilizza 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

In BigQuery esistono due tipi di località:

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

  • Per multiregione si intende 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 in 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 Cloud Run Functions sia BigQuery.

Multi-regioni

In un set di dati BigQuery multiregionale (US, EU), puoi creare una funzione remota solo se 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 multi-regione US di BigQuery 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 multi-regione EU di BigQuery può utilizzare solo una funzione Cloud Run di cui è stato eseguito il deployment in una singola regione negli stati membri dell'Unione Europea, ad esempio europe-north1, europe-west3 e così via.

Per saperne di più sulle regioni e sulle multi-regioni BigQuery, consulta la pagina Località dei set di dati. Per saperne di più sulle regioni di Cloud Run Functions, consulta la pagina Località di Cloud Run Functions.

Connessioni

Sia per una località a regione singola che per una località multiregionale, puoi creare una funzione remota solo nella stessa località della connessione che utilizzi. Ad esempio, per creare una funzione remota nella multi-regione US, utilizza una connessione situata nella multi-regione US.

Prezzi

Utilizzo dei Controlli di servizio VPC

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

  1. Creare un perimetro di servizio.

  2. Aggiungi al perimetro il progetto BigQuery della query che utilizza 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 maggiori dettagli, consulta Controlli di servizio VPC di Cloud Run Functions e Controlli di servizio VPC di Cloud Run.

Best practice per le funzioni remote

  • Pre-filtra l'input: se puoi filtrare l'input prima di passarlo a una funzione remota, la query sarà probabilmente più rapida ed economica.

  • Mantieni la scalabilità della 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 Cloud Run Functions 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 Cloud Run Functions per migliorare le prestazioni. Le query delle funzioni remote che interagiscono con una funzione Cloud Run con latenza elevata potrebbero non riuscire a causa di un timeout.

  • Implementa l'endpoint in modo che restituisca 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 rilevare tutte le eccezioni nel codice della funzione. In caso contrario, il framework del servizio HTTP potrebbe restituire automaticamente l'errore 500 per qualsiasi eccezione non rilevata. Potresti comunque visualizzare richieste HTTP ripetute 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 con esito negativo. 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

Utilizza le seguenti informazioni per risolvere i problemi relativi alle quote con le funzioni remote.

Numero massimo di query simultanee che contengono funzioni remote

BigQuery restituisce questo errore quando il numero di query simultanee che contengono funzioni remote supera il limite.

Per scoprire di più sui limiti delle funzioni remote, consulta Funzioni remote.

Messaggio di errore

Exceeded rate limits: too many concurrent queries with remote functions for
this project

Questo limite può essere aumentato. Prova prima le soluzioni alternative e le best practice.

Diagnosi

Per visualizzare i limiti per le query simultanee che contengono funzioni remote, consulta Limiti delle funzioni remote.

Risoluzione

  • Quando utilizzi le funzioni remote, segui le best practice per le funzioni remote.
  • Puoi richiedere un aumento della quota contattando l'assistenza o il team di vendita. La revisione e l'elaborazione della richiesta potrebbero richiedere diversi giorni. Ti consigliamo di indicare la priorità, il caso d'uso e l'ID progetto nella richiesta.