Crear una Cloud Run Function que use BigQuery para enviar una consulta y devolver resultados

En este instructivo, se muestra cómo escribir una Cloud Run Function HTTP que envía una consulta a BigQuery.

Objetivos

En este instructivo, podrás:

  1. Prepara la aplicación que envía una consulta a BigQuery.
  2. Implementa la función con un activador HTTP.
  3. Prueba la función.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Antes de comenzar

  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 tu entorno de desarrollo de Cloud Run en tu Google Cloud proyecto.

  8. Si estás bajo una política de la organización de restricción de dominios que restringe las invocaciones no autenticadas para tu proyecto, deberás acceder al servicio implementado como se describe en Prueba servicios privados.

    9. Roles requeridos

    Para obtener los permisos que necesitas para implementar servicios de Cloud Run desde la fuente, pídele a tu administrador que te otorgue los siguientes roles de IAM:

    Para obtener una lista de los roles y los permisos de IAM asociados con Cloud Run, consulta los roles de IAM de Cloud Run y los permisos de IAM de Cloud Run. Si tu servicio de Cloud Run interactúa con las APIs deGoogle Cloud , como las bibliotecas cliente de Cloud, consulta la guía de configuración de identidades del servicio. Para obtener más información sobre cómo otorgar roles, consulta permisos de implementación y administra el acceso.

    Roles para la cuenta de servicio de Cloud Build

    Tú o tu administrador deben otorgar a la cuenta de servicio de Cloud Build el siguiente rol de IAM.

    Haz clic para ver los roles necesarios para la cuenta de servicio de Cloud Build

    Cloud Build usa automáticamente la cuenta de servicio predeterminada de Compute Engine como la cuenta de servicio predeterminada de Cloud Build para compilar tu código fuente y el recurso de Cloud Run, a menos que anules este comportamiento. Para que Cloud Build compile tus fuentes, pídele a tu administrador que otorgue el rol de Compilador de Cloud Run (roles/run.builder) a la cuenta de servicio predeterminada de Compute Engine en tu proyecto:

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

    Reemplaza PROJECT_NUMBER por el número de tu proyecto Google Cloudy PROJECT_ID por el ID del proyecto proyecto Google Cloud. Para obtener instrucciones detalladas sobre cómo encontrar el ID y el número de tu proyecto, consulta Crea y administra proyectos.

    El otorgamiento del rol de compilador de Cloud Run a la cuenta de servicio predeterminada de Compute Engine tarda un par de minutos en propagarse.

Prepara la aplicación

  1. Clona el repositorio de la aplicación de muestra en tu máquina local:

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

    Como alternativa, descarga la muestra como un archivo ZIP y extráelo.

  2. Dirígete al directorio que contiene el código de muestra:

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

  3. Ve el código de muestra. La muestra envía una consulta de palabras que ocurren al menos 400 veces en el conjunto de datos especificado y muestra el resultado.

    // 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}`);
  }
});

Implementa la función

Para implementar la función con un activador HTTP, haz lo siguiente:

  1. Ejecuta el siguiente comando en el directorio que contiene el código de muestra:

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

    Reemplaza lo siguiente:

    • FUNCTION por el nombre de la función que implementas, por ejemplo, my-bigquery-function. Puedes omitir este parámetro por completo, pero se te solicitará el nombre si lo haces.

    • FUNCTION_ENTRYPOINT por el punto de entrada a tu función en tu código fuente. Este es el código que ejecuta Cloud Run cuando se ejecuta tu función. El valor de esta marca debe ser un nombre de función o un nombre de clase completamente calificado que exista en tu código fuente. El punto de entrada que debes especificar para la función de muestra es helloBigQuery.

    • BASE_IMAGE con el entorno de la imagen base de tu función, por ejemplo, nodejs22. Para obtener detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base de los entornos de ejecución.

    • REGION con la región de Google Clouden la que deseas implementar tu función Por ejemplo, europe-west1.

    Opcional:

    • Si creas una función de HTTP pública, por ejemplo, un webhook, especifica la marca --allow-unauthenticated. Esta marca asigna el rol de invocador de IAM de Cloud Run al identificador especial allUser. Puedes usar IAM para editar esta configuración más adelante una vez que hayas creado el servicio.

Prueba la función

  1. Cuando la función termine de implementarse, copia la propiedad uri.

  2. Visita este URI en tu navegador.

    Deberías ver una lista de las palabras que coinciden con los criterios de la consulta y cuántas veces aparece cada palabra en el conjunto de datos de destino.

Limpia

Para evitar cargos adicionales en tu cuenta de Google Cloud , borra todos los recursos que implementaste con este instructivo.

Borra el proyecto

Si creaste un proyecto nuevo para este instructivo, bórralo. Si usaste un proyecto existente y necesitas conservarlo sin los cambios que agregaste en este instructivo, borra los recursos que creaste para el instructivo.

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, sigue estos pasos:

  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.

Elimina recursos de instructivos

  1. Borra el servicio de Cloud Run que implementaste en este instructivo. Los servicios de Cloud Run no generan costos hasta que reciben solicitudes.

    Para borrar tu servicio de Cloud Run, ejecuta el siguiente comando:

    gcloud run services delete SERVICE-NAME

    SERVICE-NAME por el nombre del servicio

    También puedes borrar los servicios de Cloud Run desde la consola deGoogle Cloud .

  2. Quita la configuración de región predeterminada de gcloud que agregaste durante la configuración del instructivo:

     gcloud config unset run/region

  3. Quita la configuración del proyecto:

     gcloud config unset project