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. Prepara l'applicazione che invia una query a BigQuery.
  2. Esegui il deployment della funzione con un trigger HTTP.
  3. Testa 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 utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  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 (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 (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. Enable the Artifact Registry, Cloud Run Admin API, and Cloud Build APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

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

  8. Se il tuo progetto è soggetto a un criterio dell'organizzazione con restrizioni di dominio che limitano le chiamate non autenticate, dovrai accedere al servizio di cui è stato eseguito il deployment come descritto in Testare i servizi privati.

    9. 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 ulteriori informazioni sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestire l'accesso.

    Ruoli per il account di servizio Cloud Build

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

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

    Cloud Build utilizza automaticamente l'account di servizio predefinito di Compute Engine come service account Cloud Build predefinito per creare il codice sorgente e la risorsa Cloud Run, a meno che tu non esegua l'override di questo comportamento. Per consentire a Cloud Build di creare le tue origini, chiedi all'amministratore di concedere il ruolo Cloud Run Builder (roles/run.builder) al account di servizio predefinito di Compute Engine sul 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 numero del tuo progetto Google Cloude PROJECT_ID con l'ID del tuo progetto Google Cloud. Per istruzioni dettagliate su come trovare l'ID progetto e il numero di progetto, vedi Creazione e gestione dei progetti.

    La concessione del ruolo Cloud Run Builder all'account di servizio Compute Engine predefinito richiede un paio di minuti per la propagazione.

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 il campione come file ZIP ed estrailo.

  2. Passa alla directory che contiene il codice di esempio:

    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 il seguente 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 che 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 tua funzione nel codice sorgente. Questo è il codice eseguito da Cloud Run 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. Il punto di ingresso che devi specificare per la funzione di esempio è helloBigQuery.

    • BASE_IMAGE con l'ambiente dell'immagine di base per la tua funzione, ad esempio nodejs22. Per informazioni dettagliate sulle immagini di base e sui pacchetti inclusi in ogni immagine, consulta 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 Invoker IAM di Cloud Run all'identificatore speciale allUser. Puoi utilizzare IAM per modificare questa impostazione in un secondo momento dopo aver creato il servizio.

Testa la funzione

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

  2. Visita questo URI nel browser.

    Dovresti visualizzare un elenco delle parole che corrispondono ai criteri della query e quante volte ogni parola compare nel set di dati di destinazione.

Esegui la pulizia

Per evitare costi aggiuntivi al tuo account Google Cloud , elimina tutte le risorse che hai implementato 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 che hai aggiunto in questo tutorial, elimina le risorse che hai creato per il tutorial.

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

Per eliminare il progetto:

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Eliminare 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 tuo servizio.

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

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

     gcloud config unset run/region

  3. Rimuovi la configurazione del progetto:

     gcloud config unset project