Cómo usar las APIs de BigQuery para principiantes

Google BigQuery ha revolucionado la forma en que las organizaciones gestionan el análisis de datos a gran escala. Su arquitectura sin servidor, su escalabilidad y su interfaz SQL familiar lo convierten en una herramienta poderosa para obtener información de conjuntos de datos masivos. Si bien interactuar con BigQuery a través de Google Cloud Console o la herramienta de línea de comandos bq es común, el verdadero poder de la automatización, la integración y el desarrollo de aplicaciones personalizadas se desbloquea a través de su conjunto integral de interfaces de programación de aplicaciones (API).

Esta guía proporciona una exploración paso a paso de cómo usar las API de BigQuery, lo que le permite interactuar mediante programación con su almacén de datos, crear canalizaciones de datos, integrar BigQuery en sus aplicaciones y administrar los recursos de manera efectiva. Cubriremos los diferentes tipos de API disponibles, cómo configurar su entorno, ejemplos prácticos utilizando la biblioteca de cliente de Python e introduciremos API especializadas para casos de uso avanzados.

💡

¿Quiere una excelente herramienta de prueba de API que genere una hermosa documentación de API?

¿Quiere una plataforma integrada todo en uno para que su equipo de desarrolladores trabaje en conjunto con la máxima productividad?

¡Apidog ofrece todas sus demandas y reemplaza a Postman a un precio mucho más asequible!

button

Comprensión de las API de BigQuery

Antes de sumergirse en el código, es crucial comprender los conceptos básicos y las diferentes formas en que puede interactuar con BigQuery mediante programación.

Conceptos básicos de BigQuery:

Proyecto: El contenedor de nivel superior en Google Cloud, que contiene todos sus recursos, incluidos los conjuntos de datos, las tablas y los trabajos de BigQuery. La facturación y los permisos generalmente se administran a nivel de proyecto.
Conjunto de datos: Un contenedor para tablas y vistas dentro de un proyecto específico. Los conjuntos de datos ayudan a organizar sus datos y controlar el acceso. Piense en ellos como esquemas o bases de datos en los sistemas tradicionales.
Tabla: Almacena sus datos estructurados en filas y columnas con un esquema definido. BigQuery admite varios tipos de datos y campos anidados/repetidos.
Trabajo: Representa acciones asíncronas realizadas en BigQuery, como ejecutar consultas, cargar datos, exportar datos o copiar tablas. Las API le permiten iniciar, supervisar y administrar estos trabajos.

Tipos de API de BigQuery:

BigQuery ofrece varias formas de interactuar con sus servicios mediante programación:

API REST: Esta es la API fundamental construida sobre HTTP y JSON. Proporciona acceso directo a los recursos y operaciones de BigQuery. Puede interactuar con ella utilizando solicitudes HTTP estándar (GET, POST, PUT, DELETE) dirigidas a puntos finales específicos (por ejemplo, https://bigquery.googleapis.com/bigquery/v2/projects/{projectId}/datasets). Si bien es potente y ofrece un control preciso, el uso directo de la API REST requiere el manejo manual de la autenticación, el formato de la solicitud, el análisis de la respuesta y el manejo de errores. La autenticación generalmente implica tokens de acceso OAuth 2.0.

Bibliotecas de cliente: Google proporciona bibliotecas de cliente de alto nivel para varios lenguajes de programación populares (incluidos Python, Java, Go, Node.js, C#, PHP, Ruby). Estas bibliotecas envuelven la API REST subyacente, ofreciendo una experiencia más idiomática y amigable para el desarrollador. Simplifican las tareas comunes, manejan la autenticación (a menudo automáticamente a través de las credenciales predeterminadas de la aplicación), administran los reintentos y reducen la cantidad de código repetitivo que necesita escribir. Este es el enfoque recomendado para la mayoría del desarrollo de aplicaciones.

API especializadas: Para tareas específicas de alto rendimiento o especializadas, BigQuery ofrece API dedicadas:

API de lectura de almacenamiento de BigQuery: Diseñada para la lectura de datos de alto rendimiento directamente desde el almacenamiento administrado de BigQuery. Es significativamente más rápido que la exportación de resultados de consultas estándar, especialmente para conjuntos de datos grandes, y se integra bien con marcos de procesamiento de datos como Apache Spark, Apache Beam y Pandas. Permite la lectura paralela a través de múltiples flujos.
API de conexión de BigQuery: Le permite crear y administrar conexiones a fuentes de datos externas, como Cloud SQL, Spanner o Cloud Storage. Esto le permite consultar datos en estos sistemas externos directamente desde BigQuery utilizando la función EXTERNAL_QUERY, sin necesidad de cargar los datos en BigQuery primero.
API de Analytics Hub: Facilita el intercambio de datos seguro y escalable entre diferentes organizaciones o unidades de negocio. Le permite crear "Listados" (referencias compartibles a conjuntos de datos) dentro de "Intercambios de datos". Los consumidores pueden suscribirse a estos listados para acceder a los datos compartidos dentro de sus propios proyectos.
API de BigLake: Se utiliza para administrar tablas de BigLake. BigLake le permite crear tablas en BigQuery que operan sobre datos almacenados en formatos abiertos (como Parquet, ORC, Avro) en lagos de datos (principalmente Google Cloud Storage). Esto proporciona una interfaz unificada para consultar tanto el almacenamiento administrado de BigQuery como el almacenamiento del lago de datos con seguridad y gobernanza consistentes.

Configuración de su entorno

Antes de que pueda comenzar a realizar llamadas a la API, debe configurar su entorno local o de servidor.

Requisitos previos:

Cuenta de Google Cloud: Necesita una cuenta activa de Google Cloud.
Proyecto de Google Cloud: Cree un nuevo proyecto o seleccione uno existente en Google Cloud Console. Anote su ID de proyecto.
Habilitar la API de BigQuery: Asegúrese de que la API de BigQuery esté habilitada para su proyecto. Puede hacerlo a través de Cloud Console (API y servicios > Biblioteca > Buscar "API de BigQuery" > Habilitar). Es posible que también deba habilitar otras API como la API de lectura de almacenamiento de BigQuery o la API de conexión de BigQuery, según su caso de uso.
Facturación: Asegúrese de que la facturación esté habilitada para su proyecto. Las operaciones de BigQuery incurren en costos basados en el almacenamiento de datos, el análisis procesado y las inserciones de transmisión.

Autenticación:

Su aplicación necesita autenticarse en Google Cloud para demostrar su identidad y autorización para acceder a los recursos de BigQuery. El método recomendado para la mayoría de los escenarios son las credenciales predeterminadas de la aplicación (ADC).

Credenciales predeterminadas de la aplicación (ADC): Esta estrategia permite que su aplicación encuentre credenciales automáticamente según el entorno en el que se está ejecutando, sin necesidad de incrustar claves directamente en el código.
Desarrollo local: Instale la CLI de Google Cloud (gcloud). Ejecute el comando gcloud auth application-default login. Esto abrirá una ventana del navegador para que inicie sesión con su cuenta de Google, otorgando al SDK acceso a sus credenciales. Las bibliotecas de cliente detectarán automáticamente estas credenciales.
Compute Engine, Cloud Functions, App Engine, etc.: ADC utiliza automáticamente la cuenta de servicio asociada con el recurso donde se está ejecutando su código.
Cuentas de servicio: Para aplicaciones que se ejecutan fuera de Google Cloud o que requieren permisos específicos, puede utilizar cuentas de servicio.

Cree una cuenta de servicio en Cloud Console (IAM y administración > Cuentas de servicio).
Otorgue los roles de BigQuery necesarios (por ejemplo, Editor de datos de BigQuery, Usuario de trabajos de BigQuery, Usuario de BigQuery) a la cuenta de servicio.
Descargue el archivo de clave de la cuenta de servicio (formato JSON).
Establezca la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta absoluta del archivo de clave JSON descargado. Las bibliotecas de cliente utilizarán automáticamente este archivo de clave para la autenticación si la variable de entorno está establecida.

Instalación de bibliotecas de cliente (ejemplo de Python):

Nos centraremos en Python para nuestros ejemplos. Puede instalar las bibliotecas necesarias utilizando pip:

pip install google-cloud-bigquery
# Opcional: Instale la biblioteca de la API de almacenamiento para lecturas más rápidas
pip install google-cloud-bigquery-storage
# Opcional: Instale la integración de pandas y db-dtypes para un mejor manejo de tipos
pip install pandas db-dtypes pyarrow

Asegúrese de tener Python instalado (se recomienda la versión 3.7+ para las últimas características de la biblioteca).

Uso de la biblioteca de cliente de BigQuery (ejemplos de Python)

Ahora, exploremos las operaciones comunes de BigQuery utilizando la biblioteca de Python google-cloud-bigquery.

1. Importación e inicialización del cliente:

Primero, importe la biblioteca. Luego, cree una instancia de cliente. Si ADC está configurado correctamente, el cliente se autenticará automáticamente.

from google.cloud import bigquery
import pandas as pd

# Construya un objeto cliente de BigQuery.
# Si GOOGLE_APPLICATION_CREDENTIALS está configurado, utiliza la cuenta de servicio.
# Si se ejecutó gcloud auth application-default login, utiliza esas credenciales.
# Si se ejecuta en la infraestructura de GCP, utiliza la cuenta de servicio de la instancia.
client = bigquery.Client()

# Puede especificar explícitamente el ID del proyecto si es necesario,
# de lo contrario, a menudo se infiere del entorno/credenciales de ADC.
# client = bigquery.Client(project='your-project-id')

print("Cliente creado con éxito.")

2. Ejecución de consultas:

La operación más común es ejecutar consultas SQL.

Consulta síncrona simple: Para consultas que se espera que se completen rápidamente. query_and_wait() envía la consulta y espera los resultados.

# Defina su consulta SQL
query = """
    SELECT name, SUM(number) as total_people
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE state = 'TX'
    GROUP BY name, state
    ORDER BY total_people DESC
    LIMIT 10
"""

# Realice una solicitud de API y espere a que se complete el trabajo.
query_job = client.query(query)  # Solicitud de API
print(f"Trabajo iniciado: {query_job.job_id}")

# Espere a que se complete el trabajo y obtenga los resultados.
rows = query_job.result()  # Espera a que se complete el trabajo.

print("\nLos 10 nombres principales en TX (1910-2013):")
for row in rows:
    # Se puede acceder a los valores de fila por nombre de campo o índice.
    print(f"Nombre: {row.name}, Conteo: {row['total_people']}") # Acceso por atributo o clave

# Convierta los resultados en un DataFrame de Pandas
df = rows.to_dataframe()
print("\nResultados como DataFrame de Pandas:")
print(df.head())

Consultas asíncronas: Para consultas de larga duración, inicie el trabajo y verifique su estado más tarde.

query = """
    SELECT corpus, COUNT(word) as distinct_words
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus
    ORDER BY distinct_words DESC;
"""
job_config = bigquery.QueryJobConfig(
    # Utilice la sintaxis SQL estándar para las consultas.
    use_legacy_sql=False
)

# Inicie la consulta, pasando la configuración adicional.
query_job = client.query(query, job_config=job_config) # No espera
print(f"Trabajo asíncrono iniciado: {query_job.job_id}")

# --- Más adelante en su aplicación ---
# Verifique el estado del trabajo (opcional)
# from google.cloud.exceptions import NotFound
# try:
#     job = client.get_job(query_job.job_id, location=query_job.location)
#     print(f"Estado del trabajo {job.job_id}: {job.state}")
#     if job.state == "DONE":
#         if job.error_result:
#             print(f"Trabajo fallido: {job.errors}")
#         else:
#             results = job.result() # Obtenga los resultados
#             print("Resultados obtenidos.")
#             # Procese los resultados...
# except NotFound:
#     print(f"Trabajo {query_job.job_id} no encontrado.")

# O simplemente espere a que se complete cuando sea necesario
results = query_job.result() # Esto se bloqueará hasta que se complete el trabajo
print("Trabajo asíncrono completado.")
for row in results:
    print(f"Corpus: {row.corpus}, Palabras distintas: {row.distinct_words}")

Consultas parametrizadas: Esencial para la seguridad (prevención de la inyección SQL) al incorporar la entrada del usuario en las consultas.

from google.cloud.bigquery import ScalarQueryParameter, ArrayQueryParameter, StructQueryParameter, QueryJobConfig

# Ejemplo: Encuentre nombres que comiencen con un prefijo específico en un estado determinado
state_param = "NY"
prefix_param = "Ma"
min_count_param = 1000

query = """
    SELECT name, SUM(number) as total_people
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE state = @state_abbr AND name LIKE @name_prefix
    GROUP BY name
    HAVING total_people >= @min_count
    ORDER BY total_people DESC;
"""

job_config = QueryJobConfig(
    query_parameters=[
        ScalarQueryParameter("state_abbr", "STRING", state_param),
        # Utilice 'val%' para el operador LIKE
        ScalarQueryParameter("name_prefix", "STRING", f"{prefix_param}%"),
        ScalarQueryParameter("min_count", "INT64", min_count_param),
    ]
)

query_job = client.query(query, job_config=job_config)
print(f"Trabajo de consulta parametrizada iniciado: {query_job.job_id}")

rows = query_job.result()

print(f"\nNombres que comienzan con '{prefix_param}' en {state_param} con >= {min_count_param} personas:")
for row in rows:
    print(f"Nombre: {row.name}, Conteo: {row.total_people}")

3. Administración de conjuntos de datos:

Puede crear, enumerar, obtener detalles y eliminar conjuntos de datos.

# Defina el ID del conjunto de datos y la ubicación
project_id = client.project
dataset_id = f"{project_id}.my_new_dataset"
dataset_location = "US" # por ejemplo, "US", "EU", "asia-northeast1"

# Construya un objeto Dataset completo para enviar a la API.
dataset = bigquery.Dataset(dataset_id)
dataset.location = dataset_location
dataset.description = "Conjunto de datos creado a través de la biblioteca de cliente de Python"

try:
    # Realice una solicitud de API para crear el conjunto de datos.
    dataset = client.create_dataset(dataset, timeout=30)  # Realice una solicitud de API.
    print(f"Conjunto de datos creado {client.project}.{dataset.dataset_id}")

    # Enumere los conjuntos de datos en el proyecto
    print("\nConjuntos de datos en el proyecto:")
    datasets = list(client.list_datasets()) # Solicitud de API
    if datasets:
        for ds in datasets:
            print(f"\t{ds.dataset_id}")
    else:
        print(f"\tEl proyecto {client.project} no contiene ningún conjunto de datos.")

    # Obtenga información del conjunto de datos
    retrieved_dataset = client.get_dataset(dataset_id) # Solicitud de API
    print(f"\nInformación del conjunto de datos recuperado para {dataset_id}:")
    print(f"\tDescripción: {retrieved_dataset.description}")
    print(f"\tUbicación: {retrieved_dataset.location}")

except Exception as e:
    print(f"Error durante las operaciones del conjunto de datos: {e}")

finally:
    # Limpie: Elimine el conjunto de datos
    try:
        client.delete_dataset(
            dataset_id, delete_contents=True, not_found_ok=True
        )  # Solicitud de API
        print(f"\nConjunto de datos '{dataset_id}' eliminado con éxito.")
    except Exception as e:
         print(f"Error al eliminar el conjunto de datos {dataset_id}: {e}")

4. Administración de tablas:

Existen operaciones similares para las tablas: crear tablas (definir el esquema), cargar datos, obtener metadatos y eliminar tablas.

# Utilizando el ID del conjunto de datos creado anteriormente (asegúrese de que exista o elimine el paso de eliminación anterior)
dataset_id_for_table = "my_new_dataset" # Utilice un ID de conjunto de datos válido
table_id = f"{client.project}.{dataset_id_for_table}.my_new_table"

# Defina el esquema
schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
    bigquery.SchemaField("email", "STRING", mode="NULLABLE"),
]

# Cree la tabla
table = bigquery.Table(table_id, schema=schema)
try:
    # Asegúrese de que el conjunto de datos exista primero
    client.create_dataset(dataset_id_for_table, exists_ok=True)

    table = client.create_table(table)  # Solicitud de API
    print(
        f"Tabla creada {table.project}.{table.dataset_id}.{table.table_id}"
    )

    # --- Carga de datos (ejemplo: desde DataFrame de Pandas) ---
    data = {'full_name': ['Alice Smith', 'Bob Johnson'],
            'age': [30, 45],
            'email': ['alice@example.com', None]}
    dataframe = pd.DataFrame(data)

    job_config = bigquery.LoadJobConfig(
        # Se recomienda especificar el esquema, asegura los tipos adecuados
        schema=schema,
        # Opcional: sobrescriba los datos de la tabla
        write_disposition="WRITE_TRUNCATE",
        # O agregue: write_disposition="WRITE_APPEND",
    )

    load_job = client.load_table_from_dataframe(
        dataframe, table_id, job_config=job_config
    )  # Solicitud de API
    print(f"Iniciando el trabajo {load_job.job_id} para cargar datos desde DataFrame")

    load_job.result()  # Espera a que se complete el trabajo.
    print("Trabajo de carga de DataFrame finalizado.")

    destination_table = client.get_table(table_id) # Solicitud de API
    print(f"Se cargaron {destination_table.num_rows} filas en la tabla {table_id}")

    # --- Carga de datos (ejemplo: desde Google Cloud Storage URI) ---
    # Asuma que existe un archivo CSV gs://your-bucket/data.csv con datos compatibles
    # uri = "gs://your-bucket/data.csv"
    # job_config_gcs = bigquery.LoadJobConfig(
    #     schema=schema,
    #     skip_leading_rows=1, # Omita la fila de encabezado
    #     source_format=bigquery.SourceFormat.CSV,
    #     write_disposition="WRITE_APPEND", # Agregue a los datos existentes
    # )
    # load_job_gcs = client.load_table_from_uri(
    #     uri, table_id, job_config=job_config_gcs
    # )
    # print(f"Iniciando el trabajo {load_job_gcs.job_id} para cargar datos desde GCS")
    # load_job_gcs.result()
    # print("Trabajo de carga de GCS finalizado.")
    # destination_table = client.get_table(table_id)
    # print(f"Filas totales después de la carga de GCS: {destination_table.num_rows}")

except Exception as e:
    print(f"Error durante las operaciones de la tabla: {e}")

finally:
    # Limpie: Elimine la tabla
    try:
        client.delete_table(table_id, not_found_ok=True)  # Solicitud de API
        print(f"Tabla '{table_id}' eliminada con éxito.")
        # Opcionalmente, elimine el conjunto de datos nuevamente si fue solo para este ejemplo
        # client.delete_dataset(dataset_id_for_table, delete_contents=True, not_found_ok=True)
        # print(f"Conjunto de datos '{dataset_id_for_table}' eliminado con éxito.")
    except Exception as e:
        print(f"Error al eliminar la tabla {table_id}: {e}")

5. Trabajo con trabajos:

Todas las operaciones asíncronas (consulta, carga, exportación, copia) crean recursos de trabajo. Puede enumerar y administrar estos trabajos.

# Enumere los trabajos recientes
print("\nTrabajos recientes de BigQuery:")
for job in client.list_jobs(max_results=10): # Solicitud de API
    print(f"ID del trabajo: {job.job_id}, Tipo: {job.job_type}, Estado: {job.state}, Creado: {job.created}")

# Obtenga un trabajo específico (reemplace con un ID de trabajo válido de ejecuciones anteriores)
# try:
#     job_id_to_get = "..." # Reemplace con un ID de trabajo real
#     location = "US"      # Reemplace con la ubicación del trabajo si no es la predeterminada
#     retrieved_job = client.get_job(job_id_to_get, location=location) # Solicitud de API
#     print(f"\nDetalles del trabajo {retrieved_job.job_id}:")
#     print(f"\tEstado: {retrieved_job.state}")
#     if retrieved_job.error_result:
#         print(f"\tError: {retrieved_job.errors}")
# except NotFound:
#     print(f"Trabajo {job_id_to_get} no encontrado.")
# except Exception as e:
#     print(f"Error al recuperar el trabajo: {e}")

Aprovechamiento de API especializadas (conceptos y casos de uso)

Si bien la biblioteca de cliente principal cubre muchos casos de uso, las API especializadas ofrecen un rendimiento o funcionalidad mejorados para tareas específicas.

1. API de lectura de almacenamiento de BigQuery (Python):

Propósito: Recuperación de datos extremadamente rápida de tablas de BigQuery, evitando el motor de ejecución de consultas estándar. Ideal para exportar conjuntos de datos grandes o alimentar datos en canalizaciones de capacitación de ML o marcos de procesamiento de datos.
Cómo funciona: Crea una ReadSession especificando la tabla, las columnas y los filtros de fila. La API devuelve uno o más Streams. Lee datos (generalmente en formato Apache Arrow o Avro) de estos flujos, a menudo en paralelo.
Biblioteca de cliente: google-cloud-bigquery-storage
Uso conceptual de Python (con integración de Pandas):

# Requiere: pip install google-cloud-bigquery-storage pyarrow pandas db-dtypes

from google.cloud import bigquery_storage_v1
from google.cloud.bigquery_storage_v1 import types, GetDataStreamRequest

# --- Uso de Pandas read_gbq (integración más simple) ---
# Esto utiliza automáticamente la API de almacenamiento si está instalada y es beneficiosa
# table_id_read = "bigquery-public-data.usa_names.usa_1910_2013"
# cols_to_read = ["name", "number", "state"]
# row_filter = "state = 'CA' AND number > 5000"
#
# try:
#      df_storage = pd.read_gbq(
#          table_id_read,
#          project_id=client.project,
#          columns=cols_to_read,
#          row_filter=row_filter,
#          use_bqstorage_api=True, # Solicite explícitamente la API de almacenamiento
#          progress_bar_type='tqdm' # Barra de progreso opcional
#      )
#      print("\nLea datos utilizando la API de almacenamiento a través de pandas.read_gbq:")
#      print(df_storage.head())
#      print(f"Lea {len(df_storage)} filas.")
# except Exception as e:
#      print(f"Error al leer con la API de almacenamiento a través de read_gbq: {e}")


# --- Uso manual de la API de almacenamiento (más control) ---
# bqstorageclient = bigquery_storage_v1.BigQueryReadClient()
# table = f"projects/{project_id}/datasets/{dataset_id}/tables/{table_name}" # Reemplace con los detalles de su tabla

# requested_session = types.ReadSession(
#     table=table,
#     data_format=types.DataFormat.ARROW,
#     read_options=types.ReadSession.TableReadOptions(
#         selected_fields=["col1", "col2"], # Especifique las columnas
#         row_restriction="col1 > 100"     # Especifique el filtro
#     ),
# )
# parent = f"projects/{project_id}"

# read_session = bqstorageclient.create_read_session(
#     parent=parent,
#     read_session=requested_session,
#     max_stream_count=1, # Solicite el número de flujos paralelos
# )

# stream = read_session.streams[0]
# reader = bqstorageclient.read_rows(stream.name)
# frames = [message.arrow_record_batch for message in reader.messages()]
# if frames:
#     arrow_table = pa.Table.from_batches(frames)
#     df_manual = arrow_table.to_pandas()
#     print("\nLea datos manualmente utilizando la API de almacenamiento:")
#     print(df_manual.head())
# else:
#     print("No se leyeron datos utilizando la API de almacenamiento manual.")

2. API de conexión de BigQuery:

Propósito: Consulte fuentes de datos externas (Cloud SQL, Spanner, Cloud Storage) directamente desde BigQuery sin movimiento de datos.
Cómo funciona:

Utilice la API (o la herramienta Cloud Console/bq) para crear un recurso Connection, especificando el tipo y los detalles de la fuente externa.
Otorgue a la cuenta de servicio de la conexión los permisos apropiados en el recurso externo (por ejemplo, el rol de usuario de Cloud SQL).
Utilice la función EXTERNAL_QUERY("connection_id", "external_sql_query") dentro de su SQL de BigQuery.

Biblioteca de cliente: google-cloud-bigquery-connection proporciona métodos como create_connection, get_connection, list_connections, delete_connection.

3. API de Analytics Hub:

Propósito: Comparta de forma segura conjuntos de datos seleccionados entre organizaciones o equipos.
Conceptos clave:
Intercambio de datos: Un contenedor para compartir datos. Puede ser público o privado.
Listado: Una referencia a un conjunto de datos específico de BigQuery (o potencialmente una vista/tabla en el futuro) que se comparte dentro de un intercambio. Los editores crean listados; los suscriptores acceden a ellos.
API: Disponible a través de REST y bibliotecas de cliente (por ejemplo, google-cloud-analyticshub) para administrar intercambios, listados y suscripciones mediante programación.

4. API de BigLake:

Propósito: Administre tablas de BigLake, que permiten consultar datos en Cloud Storage utilizando la interfaz y la gobernanza de BigQuery.
Cómo funciona: Defina una tabla en BigQuery que haga referencia a archivos de datos (Parquet, ORC, etc.) en un depósito de GCS. La API de BigLake (principalmente REST en la actualidad) se utiliza para crear, actualizar y administrar los metadatos de estas tablas. La consulta se realiza a través de SQL estándar de BigQuery.

Uso directo de la API REST

Si bien generalmente se prefieren las bibliotecas de cliente, puede usar la API REST directamente si:

Está utilizando un lenguaje sin una biblioteca de cliente oficial de Google.
Necesita acceso a características de vanguardia que aún no están expuestas en las bibliotecas.
Requiere un control absoluto sobre el ciclo de solicitud/respuesta HTTP.

Realización de solicitudes:

Por lo general, utilizará un cliente HTTP (como curl o la biblioteca requests de Python). Necesita:

Obtenga un token de acceso OAuth 2.0 (por ejemplo, utilizando gcloud auth print-access-token).
Construya la URL del punto final de la API correcta.
Cree el cuerpo de la solicitud JSON de acuerdo con la especificación del método de la API.
Incluya el token de acceso en el encabezado Authorization: Bearer <token>.
Maneje la respuesta HTTP (códigos de estado, análisis JSON, mensajes de error).

Ejemplo: Ejecución de una consulta a través de REST (jobs.query)

# 1. Obtenga el token de acceso
TOKEN=$(gcloud auth print-access-token)

# 2. Defina el ID del proyecto y el cuerpo de la solicitud
PROJECT_ID="your-project-id" # Reemplace con su ID de proyecto
REQUEST_BODY=$(cat <<EOF
{
  "query": "SELECT name, SUM(number) as total_people FROM \`bigquery-public-data.usa_names.usa_1910_2013\` WHERE state = 'CA' GROUP BY name ORDER BY total_people DESC LIMIT 5;",
  "useLegacySql": false
}
EOF
)

# 3. Realice la llamada a la API utilizando curl
curl -X POST \
  "https://bigquery.googleapis.com/bigquery/v2/projects/${PROJECT_ID}/jobs" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d "${REQUEST_BODY}"

# La respuesta contendrá información del trabajo, incluido el ID del trabajo.
# Luego, deberá realizar llamadas posteriores a jobs.getQueryResults
# utilizando el ID del trabajo para recuperar las filas de datos reales una vez que se complete el trabajo.

Este ejemplo solo inicia el trabajo de consulta. La recuperación de resultados requiere sondear el estado del trabajo y luego llamar al punto final jobs.getQueryResults. Esto destaca los pasos adicionales involucrados en comparación con las bibliotecas de cliente.

Mejores prácticas y consejos

Prefiera las bibliotecas de cliente: Utilice las bibliotecas de cliente de Google Cloud siempre que sea posible para simplificar, robustecer y facilitar el mantenimiento.
Utilice ADC: Confiar en las credenciales predeterminadas de la aplicación para la autenticación simplifica la implementación en diferentes entornos. Evite incrustar credenciales en el código.
Consultas parametrizadas: Utilice siempre consultas parametrizadas al incorporar entradas externas para evitar vulnerabilidades de inyección SQL.
Optimice las consultas: Escriba SQL eficiente. Evite SELECT *, utilice las cláusulas WHERE de manera efectiva, comprenda la partición y la agrupación en clústeres para el rendimiento en tablas grandes. Utilice la función de explicación del plan de consulta.
Manejo de errores: Implemente un manejo de errores robusto, especialmente para problemas de red o errores específicos de la API (por ejemplo, cuota excedida, no encontrado). Las bibliotecas de cliente a menudo incluyen mecanismos de reintento integrados para errores transitorios.
Administración de recursos: Elimine explícitamente los conjuntos de datos o las tablas