Crea una funzione Cloud Run che utilizza BigQuery per inviare una query e restituire i risultati.

Questo tutorial mostra come scrivere una funzione Cloud Run HTTP che invia una query a BigQuery.

Obiettivi

In questo tutorial, imparerai a:

  1. Preparare l'applicazione che invia una query a BigQuery.
  2. Eseguire il deployment della funzione con un trigger HTTP.
  3. Testare la funzione.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi Google Cloud utenti potrebbero avere diritto a una prova senza costi.

Prima di iniziare

  1. Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Abilita le API Artifact Registry, API Cloud Run Admin e API Cloud Build.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  7. Configura l'ambiente di sviluppo Cloud Run nel tuo Google Cloud progetto.

  8. Se sei soggetto a una policy dell'organizzazione con restrizioni di dominio che limita le chiamate non autenticate per il tuo progetto, dovrai accedere al servizio di cui hai eseguito il deployment come descritto in Testare i servizi privati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire il deployment dei servizi Cloud Run dall'origine, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se il tuo servizio Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità del servizio. Per saperne di più sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestisci l'accesso.

Ruoli per il account di servizio Cloud Build

Tu o il tuo amministratore dovete concedere al account di servizio Cloud Build il seguente ruolo IAM.

Fai clic per visualizzare i ruoli richiesti per il account di servizio Cloud Build

Per impostazione predefinita, Cloud Build utilizza automaticamente il service account predefinito di Compute Engine come account di servizio Cloud Build predefinito per creare il codice sorgente e la risorsa Cloud Run, a meno che tu non sostituisca questo comportamento. Affinché Cloud Build possa creare le tue origini, chiedi all'amministratore di concedere Cloud Run Builder (roles/run.builder) al account di servizio predefinito di Compute Engine nel tuo progetto:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/run.builder

Sostituisci PROJECT_NUMBER con il tuo Google Cloud numero del progetto e PROJECT_ID con il tuo Google Cloud ID progetto. Per istruzioni dettagliate su come trovare l'ID progetto e il numero di progetto, vedi Creazione e gestione dei progetti.

La propagazione della concessione del ruolo Cloud Run Builder al account di servizio predefinito di Compute Engine richiede alcuni minuti per propagarsi.

Prepara l'applicazione

  1. Clona il repository dell'applicazione di esempio sulla tua macchina locale:

    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

    In alternativa, scarica l'esempio come file ZIP ed estrailo.

  2. Passa alla directory che contiene il codice campione:

    cd nodejs-docs-samples/functions/v2/helloBigQuery

  3. Dai un'occhiata al codice campione. L'esempio invia una query per le parole che si verificano almeno 400 volte nel set di dati specificato e restituisce il risultato.

    // Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

const functions = require('@google-cloud/functions-framework');

/**
 * HTTP Cloud Function that returns BigQuery query results
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloBigQuery', async (req, res) => {
  // Define the SQL query
  // Queries the public Shakespeare dataset using named query parameter
  const sqlQuery = `
      SELECT word, word_count
            FROM \`bigquery-public-data.samples.shakespeare\`
            WHERE corpus = @corpus
            AND word_count >= @min_word_count
            ORDER BY word_count DESC`;

  const options = {
    query: sqlQuery,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    params: {corpus: 'romeoandjuliet', min_word_count: 400},
  };

  // Execute the query
  try {
    const [rows] = await bigquery.query(options);
    // Send the results
    res.status(200).send(rows);
  } catch (err) {
    console.error(err);
    res.status(500).send(`Error querying BigQuery: ${err}`);
  }
});

Esegui il deployment della funzione

Per eseguire il deployment della funzione con un trigger HTTP:

  1. Esegui questo comando nella directory che contiene il codice campione:

    gcloud run deploy FUNCTION \
   --source . \
   --function FUNCTION_ENTRYPOINT \
   --base-image BASE_IMAGE \
   --region REGION \
   --allow-unauthenticated

    Sostituisci:

    • FUNCTION con il nome della funzione di cui stai eseguendo il deployment, ad esempio my-bigquery-function. Puoi omettere completamente questo parametro, ma ti verrà chiesto il nome se lo ometti.

    • FUNCTION_ENTRYPOINT con l'entry point della funzione nel codice sorgente. Questo è il codice che Cloud Run esegue quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completo esistente nel codice sorgente. L'entry point che devi specificare per la funzione di esempio è helloBigQuery.

    • BASE_IMAGE con l'ambiente dell'immagine di base per la funzione, ad esempio nodejs24. Per informazioni dettagliate sulle immagini di base e sui pacchetti inclusi in ogni immagine, vedi Immagini di base dei runtime.

    • REGION con la Google Cloud regione in cui vuoi eseguire il deployment della funzione. Ad esempio, europe-west1.

    Facoltativamente,

    • Se stai creando una funzione HTTP pubblica, ad esempio un webhook, specifica il flag --allow-unauthenticated. Questo flag assegna il ruolo Cloud Run IAM Invoker all'identificatore speciale allUser. Puoi modificare questa impostazione in un secondo momento con IAM dopo aver creato il servizio.

Testa la funzione

  1. Al termine del deployment della funzione, copia la proprietà uri.

  2. Accedi all'URI dal browser.

    Dovresti visualizzare un elenco delle parole che corrispondono ai criteri della query e il numero di volte in cui ogni parola viene visualizzata nel set di dati di destinazione.

Libera spazio

Per evitare addebiti aggiuntivi al tuo Google Cloud account, elimina tutte le risorse di cui hai eseguito il deployment con questo tutorial.

Elimina il progetto

Se hai creato un nuovo progetto per questo tutorial, eliminalo. Se hai utilizzato un progetto esistente e devi conservarlo senza le modifiche aggiunte in questo tutorial, elimina le risorse create per il tutorial.

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.

Per eliminare il progetto:

  1. Nella Google Cloud console, vai alla pagina Gestisci risorse.

    Vai a Gestisci risorse

  2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
  3. Nella finestra di dialogo, digita l'ID progetto e fai clic su Chiudi per eliminare il progetto.

Elimina le risorse del tutorial

  1. Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial. I servizi Cloud Run non comportano costi finché non ricevono richieste.

    Per eliminare il servizio Cloud Run, esegui questo comando:

    gcloud run services delete SERVICE-NAME

    Sostituisci SERVICE-NAME con il nome del servizio.

    Puoi eliminare i servizi Cloud Run anche dalla Google Cloud console.

  2. Rimuovi la configurazione della regione predefinita di gcloud che hai aggiunto durante la configurazione del tutorial:

     gcloud config unset run/region

  3. Rimuovi la configurazione del progetto:

     gcloud config unset project