Etiqueta tablas y conjuntos de datos

En este documento, se describe cómo usar etiquetas para aplicar de forma condicional las políticas de Identity and Access Management (IAM) a las tablas y los conjuntos de datos de BigQuery.

Una etiqueta es un par clave-valor que puedes adjuntar directamente a una tabla o un conjunto de datos, o que una tabla o un conjunto de datos puede heredar de otros recursos de Google Cloud. Puedes aplicar políticas de forma condicional en función de si un recurso tiene una etiqueta específica. Por ejemplo, puedes otorgar de forma condicional el rol de Visualizador de datos de BigQuery a una principal en cualquier conjunto de datos con la etiqueta environment:dev.

Para obtener más información sobre el uso de etiquetas en la jerarquía de recursos de Google Cloud, consulta la Descripción general de las etiquetas.

Para otorgar permisos a muchos recursos de BigQuery relacionados al mismo tiempo, incluidos los recursos que aún no existen, considera usar las Condiciones de IAM.

Permisos necesarios

Para usar etiquetas en BigQuery, necesitas los siguientes permisos:

• Para adjuntar una etiqueta a un conjunto de datos, necesitas el permiso bigquery.datasets.createTagBinding de IAM en el conjunto de datos y el permiso resourcemanager.tagValueBindings.create a nivel del proyecto en el valor de la etiqueta que deseas adjuntar.
• Para adjuntar una etiqueta a una tabla, necesitas el permiso bigquery.tables.createTagBinding de IAM en la tabla y el permiso resourcemanager.tagValueBindings.create a nivel del proyecto en el valor de la etiqueta que deseas adjuntar.
• Para quitar una etiqueta de un conjunto de datos, necesitas el permiso bigquery.datasets.deleteTagBinding de IAM en el conjunto de datos y el permiso resourcemanager.tagValueBindings.delete a nivel de proyecto en el valor de la etiqueta que deseas borrar.
• Para quitar una etiqueta de una tabla, necesitas el permiso bigquery.tables.deleteTagBinding de IAM en la tabla y el permiso resourcemanager.tagValueBindings.delete a nivel del proyecto en el valor de la etiqueta que deseas borrar.
• Para enumerar las etiquetas adjuntas a un conjunto de datos o ver la sección Etiquetas del panel Editar detalles para un conjunto de datos, necesitas el permiso de IAM bigquery.datasets.listTagBindings.
• Para enumerar las claves de etiqueta que están asociadas con una organización o proyecto superior en el panel Editar detalles de un conjunto de datos o una tabla, necesitas el permiso resourcemanager.tagKeys.list en la clave de etiqueta el nivel superior y el permiso resourcemanager.tagKeys.get para cada clave de etiqueta.
• Para enumerar los valores de las etiquetas de las claves asociadas con una organización o un proyecto superior en el panel Editar detalles de un conjunto de datos o una tabla, necesitas el permiso resourcemanager.tagValues.list en el nivel superior del valor de la etiqueta y el permiso resourcemanager.tagValues.get para cada valor de la etiqueta

Los siguientes roles predefinidos de IAM incluyen todos los permisos de BigQuery necesarios:

• Propietario de datos de BigQuery (roles/bigquery.dataOwner)
• BigQuery Admin (roles/bigquery.admin)

Los permisos de Resource Manager se incluyen en el rol de usuario de etiquetas (roles/resourcemanager.tagUser).

Crea claves y valores de etiqueta

Antes de poder adjuntar una etiqueta, debes crear una y configurar su valor. Para crear claves y valores de etiqueta, consulta Crea una etiqueta y Agrega valores de etiquetas.

Adjunta etiquetas a un conjunto de datos

Después de crear una etiqueta, puedes adjuntarla a un conjunto de datos. Solo puedes adjuntar un valor de etiqueta a un conjunto de datos para cualquier clave de etiqueta determinada. Puedes adjuntar un máximo de 50 etiquetas a un conjunto de datos.

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y elige un conjunto de datos.

3. En la sección Información del conjunto de datos, haz clic en Editar detalles.

4. En la sección Etiquetas, selecciona las etiquetas que deseas agregar al conjunto de datos.

   Nota: La sección Etiquetas no es visible si no tienes el permiso bigquery.datasets.listTagBindings.

5. Haz clic en Guardar.

gcloud

Para adjuntar una etiqueta a un conjunto de datos mediante la línea de comandos, crea un recurso de vinculación de etiquetas con el comando gcloud resource-manager tags bindings create:

gcloud resource-manager tags bindings create \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Reemplaza lo siguiente:

• TAGVALUE_NAME: El ID permanente o el nombre con espacio de nombres del valor de la etiqueta que se adjuntará, como tagValues/4567890123 o 1234567/my_tag_key/my_tag_value
• RESOURCE_ID: El ID completo del conjunto de datos, incluido el nombre de dominio de la API (//bigquery.googleapis.com/) para identificar el tipo de recurso, por ejemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
• LOCATION: La ubicación de tu conjunto de datos

Obtén una lista de las etiquetas adjuntas a un conjunto de datos

Con los siguientes pasos, se proporciona una lista de vinculaciones de etiquetas adjuntas directamente a un conjunto de datos. No se muestran etiquetas heredadas de los recursos superiores.

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y elige un conjunto de datos.

   Las etiquetas aparecen en la sección Información del conjunto de datos.

Nota: Si tienes el permiso bigquery.datasets.listTagBindings, pero no resourcemanager.tagKeys.get y resourcemanager.tagValues.get, solo se podrá ver el ID permanente de la etiqueta.

gcloud

Para obtener una lista de vinculaciones de etiquetas adjuntas a un recurso, usa el comando gcloud resource-manager tags bindings list:

gcloud resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=LOCATION

Reemplaza lo siguiente:

• RESOURCE_ID: El ID completo del conjunto de datos, incluido el nombre de dominio de la API (//bigquery.googleapis.com/) para identificar el tipo de recurso, por ejemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset

• LOCATION: La ubicación de tu conjunto de datos

El resultado es similar a este:

name: tagBindings/%2F%2Fbigquery.googleapis.com%2Fprojects%2Fmy_project%2Fdatasets%2Fmy_dataset/tagValues/4567890123
parent: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
tagValue: tagValues/4567890123

Desvincula etiquetas de un conjunto de datos

Para desconectar una etiqueta de un recurso, borra el recurso de vinculación de etiquetas. Si necesitas borrar una etiqueta, primero debes desvincularla.

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y elige un conjunto de datos.

3. En la sección Información del conjunto de datos, haz clic en Editar detalles.

4. En la sección Etiquetas, haz clic en Borrar elemento junto a la etiqueta que deseas borrar.

5. Haz clic en Guardar.

gcloud

Para desvincular una etiqueta de un conjunto de datos mediante la línea de comandos, borra la vinculación de la etiqueta con el comando gcloud alpha resource-manager tags bindings delete:

gcloud alpha resource-manager tags bindings delete \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Reemplaza lo siguiente:

• TAGVALUE_NAME: El ID permanente o el nombre con espacio de nombres del valor de la etiqueta que se adjuntará, como tagValues/4567890123 o 1234567/my_tag_key/my_tag_value
• RESOURCE_ID: El ID completo del conjunto de datos, incluido el nombre de dominio de la API (//bigquery.googleapis.com/) para identificar el tipo de recurso, por ejemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
• LOCATION: La ubicación de tu conjunto de datos

Adjunta etiquetas cuando crees una tabla nueva

Vista previa

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Después de crear una etiqueta, puedes adjuntarla a una tabla nueva. Solo puedes adjuntar un valor de etiqueta a un conjunto de datos para cualquier clave de etiqueta determinada. Puedes adjuntar un máximo de 50 etiquetas a una tabla.

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.

3. En la sección Información del conjunto de datos, haz clic en Crear tabla.

4. Ingresa la información de la nueva tabla. Para obtener más información, consulta Crea y usa tablas.

5. En la sección Etiquetas, selecciona las etiquetas que deseas agregar a la tabla nueva. No puedes ingresar manualmente los IDs de etiqueta en este paso. Solo puedes seleccionar etiquetas de tu organización o proyecto.

6. Haz clic en Crear tabla.

bq

Usa el comando bq mk --table con la marca --add_tags:

bq mk --table \
    --schema=SCHEMA \
    --add_tags=TAGS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Reemplaza lo siguiente:

• SCHEMA: es la definición de esquema intercalado.
• TAGS: Son las etiquetas que adjuntas a la tabla nueva, separadas por comas, por ejemplo, 556741164180/env:prod,myProject/department:sales. Cada etiqueta debe tener el nombre de clave con espacio de nombres y el nombre corto del valor.
• PROJECT_ID: el ID del proyecto en el que creas una tabla.
• DATASET_ID: el ID del conjunto de datos en el que creas una tabla.
• TABLE_ID: el ID de la tabla nueva que estás creando.

API

Realiza una llamada al método tables.insert con un recurso de tabla definido e incluye las etiquetas en el campo resource_tags.

Adjunta etiquetas a una tabla existente

Vista previa

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Después de crear una etiqueta, puedes adjuntarla a una tabla existente. Solo puedes adjuntar un valor de etiqueta a una tabla para cualquier clave de etiqueta determinada. Puedes adjuntar un máximo de 50 etiquetas a una tabla.

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande el proyecto y el conjunto de datos y, luego, selecciona una tabla.

3. En la pestaña Detalles, haz clic en Editar detalles.

4. En la sección Etiquetas, selecciona las etiquetas que deseas agregar a la tabla. No puedes ingresar manualmente los IDs de etiqueta en este paso. Solo puedes seleccionar etiquetas de tu organización o proyecto.

5. Haz clic en Guardar.

bq

Usa el comando bq update con la marca --add_tags:

bq update \
    --add_tags=TAGS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Reemplaza lo siguiente:

• TAGS: las etiquetas que adjuntas a la tabla, separadas por comas, por ejemplo, 556741164180/env:prod,myProject/department:sales. Cada etiqueta debe tener el nombre de clave con espacio de nombres y el nombre corto del valor.
• PROJECT_ID: el ID del proyecto que contiene tu tabla.
• DATASET_ID: el ID del conjunto de datos que contiene tu tabla.
• TABLE_ID: el ID de la tabla que deseas actualizar.

API

Realiza una llamada al método tables.update con un recurso de tabla definido e incluye las etiquetas en el campo resource_tags.

Enumera las etiquetas adjuntas a una tabla

Vista previa

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Puedes enumerar las etiquetas que se adjuntan directamente a una tabla. Este proceso no enumera las etiquetas heredadas de los recursos superiores.

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande el proyecto y el conjunto de datos y, luego, selecciona una tabla.

   Las etiquetas se pueden ver en la pestaña Detalles.

bq

Usa el comando bq show y busca la columna tags. Si no hay etiquetas en la tabla, no se muestra la columna tags.

bq show \
    PROJECT_ID:DATASET_ID.TABLE_ID

Reemplaza lo siguiente:

• PROJECT_ID: el ID del proyecto que contiene tu tabla
• DATASET_ID: el ID del conjunto de datos que contiene tu tabla
• TABLE_ID: el ID de tu tabla

API

Realiza una llamada al método tables.get con un recurso de tabla definido y busca el campo resource_tags.

Desconecta etiquetas de una tabla

Vista previa

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para desconectar una etiqueta de una tabla, borra el recurso de vinculación de etiquetas. Si necesitas borrar una etiqueta, primero debes desvincularla.

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande el proyecto y el conjunto de datos y, luego, selecciona una tabla.

3. En la pestaña Detalles, haz clic en Editar detalles.

4. En la sección Etiquetas, quita las etiquetas que deseas desconectar de la tabla.

5. Haz clic en Guardar.

bq

Para quitar algunas etiquetas de una tabla, usa el comando bq update con la marca --remove_tags:

bq update \
    --remove_tags=TAG_KEYS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Reemplaza lo siguiente:

• TAG_KEYS: las claves de etiqueta que desconectas de la tabla, separadas por comas, por ejemplo, 556741164180/env,myProject/department. Cada clave de etiqueta debe tener el nombre de clave con espacio de nombres.
• PROJECT_ID: el ID del proyecto que contiene tu tabla.
• DATASET_ID: el ID del conjunto de datos que contiene tu tabla.
• TABLE_ID: el ID de la tabla que deseas actualizar.

Para quitar todas las etiquetas de una tabla, usa el comando bq update con la marca --clear_all_tags:

bq update \
    --clear_all_tags \
    PROJECT_ID:DATASET_ID.TABLE_ID

API

Realiza una llamada al método tables.update con un recurso de tabla definido y quita las etiquetas en el campo resource_tags. Para quitar todas las etiquetas, quita el campo resource_tags.

Borrar etiquetas

No puedes borrar una etiqueta si un conjunto de datos o una tabla hace referencia a ella. Debes desconectar todos los recursos de vinculación de etiquetas existentes antes de borrar la clave o el valor de la etiqueta. Para borrar claves y valores de etiqueta, consulta Borra etiquetas.

Ejemplo

Imagina que eres administrador de una organización. Los analistas de datos son todos miembros del grupo [e-mail], que tiene el rol de IAM de Visualizador de datos de BigQuery en el proyecto userData. Se contrata un pasante de analista de datos y, de acuerdo con la política de la empresa, solo debe tener permiso para ver el conjunto de datos anonymousData en el proyecto userData. Puedes controlar su acceso mediante etiquetas.

1. Crea una etiqueta con la clave employee_type y el valor intern:

   

2. En la consola de Google Cloud, ve a la página IAM.

   Ir a IAM

3. Ubica la fila que contiene el pasante cuyo acceso al conjunto de datos deseas restringir y haz clic en Editar principal en esa fila.

4. En el menú Rol, selecciona Visualizador de datos de BigQuery.

5. Haz clic en Agregar condición:

6. En los campos Título y Descripción, ingresa los valores que describen la condición de etiqueta de IAM que deseas crear.

7. En la pestaña Creador de condiciones, haz clic en Agregar.

8. En el menú Tipo de condición, selecciona Recurso y, luego, Etiqueta.

9. En el menú Operador, selecciona tiene el valor.

10. En el campo Ruta de valor, ingresa la ruta de valor de etiqueta en el formato ORGANIZATION/TAG_KEY/TAG_VALUE, por ejemplo, example.org/employee_type/intern.

    

    Esta condición de etiqueta de IAM restringe el acceso del pasante a los conjuntos de datos que tienen la etiqueta intern.

11. Para guardar la condición de etiqueta, haz clic en Guardar.

12. Para guardar todos los cambios que realizaste en el panel Editar permisos, haz clic en Guardar.

13. A fin de adjuntar el valor de etiqueta intern al conjunto de datos anonymousData, usa la línea de comandos para ejecutar el comando gcloud alpha resource-manager tags bindings create:

    gcloud alpha resource-manager tags bindings create \
    --tag-value=tagValues/4567890123 \
    --parent=//bigquery.googleapis.com/projects/userData/datasets/anonymousData \
    --location=US
    

Limitaciones

• Las etiquetas de tabla no son compatibles con las tablas de BigQuery Omni, las tablas de conjuntos de datos ocultos ni las tablas temporales. Además, las consultas entre regiones en BigQuery Omni no usan etiquetas durante las verificaciones de control de acceso de las tablas en otras regiones.

• No puedes usar etiquetas de tablas con la API de Cloud Resource Manager.

• Puedes adjuntar un máximo de 50 etiquetas a un conjunto de datos o una tabla.

• Las consultas comodín no son compatibles con las tablas que tienen etiquetas.

• Algunos servicios fuera de BigQuery no pueden verificar las condiciones de la etiqueta de IAM de forma correcta. Si la condición de la etiqueta es positiva, es decir, se le otorga a un usuario una función en un recurso solo si ese recurso tiene una etiqueta en particular, entonces el acceso se niega al recurso, sin importar a qué etiquetas se adjunten. Si la condición de la etiqueta es negativa, lo que significa que se otorga a un usuario una función en un recurso solo si ese recurso no tiene una etiqueta en particular, entonces la condición de la etiqueta no se verifica.

  Por ejemplo, Data Catalog no puede verificar las condiciones de la etiqueta de IAM en los conjuntos de datos de BigQuery. Supongamos que hay una política de IAM condicional que le otorga a un pasante el rol de visualizador de datos de BigQuery en los conjuntos de datos con la etiqueta employee_type=intern. Dado que esta es una condición de etiqueta positiva, el pasante no puede ver los conjuntos de datos mediante la búsqueda en Data Catalog, incluso si esos conjuntos de datos tienen la etiqueta employee_type=intern. Si la condición se cambia a una negativa, de modo que el pasante solo pueda ver los conjuntos de datos que no tienen la etiqueta employee_type=intern, entonces la verificación se omitiría por completo y el pasante podría ver los conjuntos de datos a los que normalmente no podría acceder en BigQuery.

  Práctica recomendada: Usa condiciones de etiqueta de IAM positivas en lugar de negativas para evitar otorgar funciones de manera involuntaria.

¿Qué sigue?

• Para obtener una descripción general de las etiquetas en Google Cloud, consulta Descripción general de las etiquetas.
• Para obtener más información sobre cómo usar etiquetas, consulta Crea y administra etiquetas.
• Para obtener información sobre cómo controlar el acceso a los recursos de BigQuery con condiciones de IAM, consulta Controla el acceso con Condiciones de IAM.