Crea un detector almacenado de diccionario personalizado

Los detectores de diccionarios personalizados normales son suficiente cuando tienes una lista de hasta decenas de miles de palabras o frases sensibles en las que deseas analizar tu contenido. Si tienes más de esta cantidad de palabras o frases para analizar, o si tu lista de palabras o frases cambia con frecuencia, considera crear un diccionario personalizado almacenado, que puedes usar para buscar decenas de millones de palabras o frases.

En este tema, se describe cómo crear y volver a compilar diccionarios personalizados almacenados y se presentan varias situaciones de error.

Anatomía de un diccionario personalizado almacenado

Es posible que estés familiarizado con la forma de crear un Infotipo personalizado de diccionario normal o un Infotipo personalizado de regex: configuras el Infotipo personalizado y, luego, lo usas cuando configuras tu inspección o análisis de desidentificación. Sin embargo, los diccionarios personalizados almacenados son diferentes de estos Infotipos personalizados, ya que cada diccionario personalizado almacenado tiene dos componentes:

  • Una lista de frases que creas y defines. La lista se almacena como un archivo de texto dentro de Cloud Storage o como una columna en una tabla de BigQuery.
  • Los archivos de diccionario que genera Cloud DLP se basan en tu lista de frases. Los archivos del diccionario se almacenan en Cloud Storage y se componen de una copia de los datos de la frase fuente más los filtros de Bloom que ayudan en la búsqueda y en la detección de coincidencias. No puedes editar estos archivos directamente.

Crea un nuevo diccionario personalizado almacenado

En esta sección, se describe cómo crear, editar y volver a compilar un diccionario personalizado almacenado.

Crea una lista de frases

El primer paso para crear un diccionario personalizado almacenado es crear una lista de palabras y frases. Tienes dos opciones:

  • Colocar un archivo de texto con cada palabra o frase en su propia línea en un depósito de Cloud Storage.
  • Designar una columna de una tabla de BigQuery como contenedor de las frases. Dar a cada frase su propia fila en la columna. Puedes usar una tabla de BigQuery existente, siempre y cuando todas las palabras y frases del diccionario estén en una sola columna.

Ten en cuenta que es posible ensamblar una lista de términos que sea demasiado grande para que se procese en Cloud DLP. Si ves un mensaje de error, consulta "Solución de errores", más adelante en este tema.

Crea el diccionario

Una vez que hayas creado tu lista de términos, usa Cloud DLP para crear un diccionario:

Console

  1. Crea una carpeta nueva para el diccionario en un depósito de Cloud Storage. Cloud DLP crea carpetas que contienen los archivos del diccionario en la ubicación que especifiques.
  2. En Cloud Console, abre Cloud DLP.

    Ir a la IU de Cloud DLP

  3. En el menú Create (Crear), selecciona Stored infoType (Infotipo almacenado).

    Captura de pantalla de la IU de DLP con el menú Crear y el Infotipo almacenado seleccionado.

    También puedes hacer clic en el siguiente botón:

    Crear nuevo Infotipo

La página Crear Infotipo contiene las siguientes secciones:

Configura un Infotipo

En la sección Configura un Infotipo, puedes nombrar y describir tu Infotipo personalizado de diccionario almacenado.

  • En el campo ID de Infotipo, ingresa un identificador para el Infotipo personalizado. Esta es la forma que usarás para referirte al Infotipo cuando configures tus trabajos de inspección y desidentificación. Puedes usar letras, números, guiones y guiones bajos en el nombre.
  • En el campo Nombre visible del Infotipo, ingresa un nombre para tu Infotipo personalizado. Puedes usar espacios y signos de puntuación en el nombre.
  • En el campo Descripción, ingresa una descripción de lo que detecta tu Infotipo personalizado.

Elige la ubicación de los datos

La sección Elige la ubicación de los datos es donde especificas la ubicación de la lista de palabras y frases desde las que crearás tu diccionario personalizado almacenado.

  • Elige BigQuery si las palabras y frases para buscar aparecen en una tabla de BigQuery. Recuerda que puedes designar como máximo una columna de la tabla. Ingresa el ID del proyecto, el ID del conjunto de datos y el ID de la tabla en los campos especificados. En el campo Nombre del campo, ingresa el identificador de columna.
  • Elige Google Cloud Storage si las palabras y frases que deseas buscar aparecen en un archivo de texto en Cloud Storage. Ingresa la ruta de acceso al archivo en el campo especificado.

En la sección final, se especifica una ubicación para que Cloud DLP guarde el diccionario personalizado almacenado compactado.

En el campo Depósito o carpeta de salida, ingresa la ruta de acceso en la que deseas guardar el diccionario.

Haz clic en Crear para crear el diccionario personalizado almacenado. Aparecerá la pantalla de detalles del Infotipo.

Cuando el estado es “Listo”, se genera el diccionario personalizado almacenado y el nuevo Infotipo personalizado está listo para usar.

Protocolo

  1. Crea una carpeta nueva para el diccionario en un depósito de Cloud Storage. Cloud DLP crea carpetas que contienen los archivos del diccionario en la ubicación que especifiques.
  2. Usa el método storedInfoTypes.create de la API de Cloud DLP para crear el diccionario. El método create incluye los siguientes parámetros:
    • Un objeto StoredInfoTypeConfig, que contiene la configuración del Infotipo almacenado. Encontrarás la siguiente información:
      • description: es una descripción del diccionario.
      • displayName: es el nombre que deseas asignar al diccionario.
      • LargeCustomDictionaryConfig: contiene la configuración del diccionario personalizado almacenado. Encontrarás la siguiente información:
        • BigQueryField: se especifica si tu lista de términos se almacena en BigQuery. Incluye una referencia de la tabla en la que está almacenada tu lista, además del campo que contiene cada frase del diccionario.
        • CloudStorageFileSet: se especifica si tu lista de términos se almacena en Cloud Storage. Incluye la URL a la ubicación de origen en Cloud Storage, de la siguiente manera: "gs://[PATH_TO_GS]". Se admiten comodines.
        • outputPath: es la ruta a la ubicación en un depósito de Cloud Storage para almacenar el diccionario creado.
    • storedInfoTypeId: es el identificador para el Infotipo personalizado almacenado. Este valor es la forma en que harás referencia al Infotipo personalizado almacenado cuando lo vuelvas a compilar o lo borres, o cuando lo uses en un trabajo de inspección o desidentificación. Si dejas este campo vacío, el sistema generará un identificador para ti.

A continuación, se muestra un ejemplo de JSON que, cuando se envía al método storedInfoTypes.create, crea un nuevo diccionario personalizado almacenado. En este ejemplo, le indicamos a Cloud DLP que cree un diccionario personalizado almacenado a partir de una lista de términos almacenados en la base de datos de BigQuery pública que contenga todos los nombres de usuario de GitHub usados en las confirmaciones (bigquery-public-data.samples.github_nested). La ruta de salida para el diccionario generado se establece en un depósito de Cloud Storage llamado dlptesting, y el diccionario personalizado almacenado recibe el nombre github-usernames.

Entrada de JSON:

POST https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/storedInfoTypes?key={YOUR_API_KEY}

{
  "config":{
    "displayName":"GitHub usernames",
    "description":"Dictionary of github usernames used in commits",
    "largeCustomDictionary":{
      "outputPath":{
        "path":"gs://[PATH_TO_GS]"
      },
      "bigQueryField":{
        "table":{
          "datasetId":"samples",
          "projectId":"bigquery-public-data",
          "tableId":"github_nested"
        }
      }
    }
  },
  "storedInfoTypeId":"github-usernames"
}

Vuelve a compilar el diccionario

Si deseas agregar o quitar términos o frases a tu diccionario, primero debes actualizar tu lista de términos de origen y, luego, indicarle a Cloud DLP que vuelva a compilar el diccionario.

  1. Actualiza la lista de términos de origen existente en Cloud Storage o BigQuery. Agrega, quita o cambia los términos o frases, según sea necesario.
  2. Para crear una versión nueva del diccionario, vuelve a compilarla mediante Cloud Console o con el método storedInfoTypes.patch de Cloud DLP. De esta manera, se crea una nueva versión del diccionario, que reemplaza al diccionario anterior.

Para volver a compilar el diccionario personalizado almacenado, sigue estos pasos:

Console

  1. Actualiza y guarda tu lista de términos en Cloud Storage o BigQuery.
  2. En Cloud Console, abre Cloud DLP.
  3. Haz clic en la pestaña Configuración y, luego, en Infotipos.
  4. En la pantalla Infotipos, haz clic en la pestaña Personalizar. Aquí aparecen tus Infotipos personalizados almacenados.

    Ir a la lista de Infotipos personalizados

  5. Haz clic en la fila con el Infotipo almacenado que deseas actualizar.

  6. En la pantalla de detalles del Infotipo, haz clic en Volver a compilar datos.

Cloud DLP vuelve a compilar el diccionario personalizado almacenado con los cambios que realizaste en la lista de términos de origen. Una vez que el estado del Infotipo personalizado sea “Listo”, puedes usarlo. Cualquier plantilla o activador de trabajo que use el Infotipo personalizado usará automáticamente el Infotipo personalizado que se volvió a compilar.

Protocolo

Si lo único que intentas hacer es agregar términos nuevos o borrar o cambiar los términos existentes en el diccionario personalizado almacenado, solo necesitas llamar al método storedInfoTypes.patch para volver a compilar el diccionario. Asegúrate de propagar el campo name con el nombre del recurso de la organización o del proyecto, y el Infotipo personalizado almacenado que se volverá a compilar. Proporcionaste el nombre del Infotipo almacenado cuando lo creaste en el parámetro storedInfoTypeId. Si no recuerdas el identificador del Infotipo personalizado almacenado que deseas volver a compilar, llama al método storedInfoTypes.list para ver una lista de todos los Infotipos almacenados actuales.

Los siguientes patrones representan entradas válidas para el campo name:

  • organizations/[ORG_ID]/storedInfoTypes/[STORED_INFOTYPE_ID]
  • projects/[PROJECT_ID]/storedInfoTypes/[STORED_INFOTYPE_ID]

Cuando vuelves a compilar un diccionario personalizado almacenado en una versión nueva, se borra la versión anterior. Mientras Cloud DLP actualiza el diccionario personalizado almacenado, el estado del diccionario es “pendiente”. Cuando el estado de la nueva versión del diccionario es “pendiente”, la versión anterior aún existe. Todos los análisis que ejecutes mientras se vuelve a compilar el diccionario se ejecutarán con la versión anterior.

Puedes cambiar la lista de términos de origen para un diccionario personalizado almacenado existente desde uno almacenado en una tabla de BigQuery hasta uno almacenado en un depósito de Cloud Storage, y viceversa. Usa el método storedInfoTypes.patch, pero incluye un objeto CloudStorageFileSet en LargeCustomDictionaryConfig en el que hayas usado un BigQueryField antes, o viceversa. También debes especificar el parámetro updateMask y configurarlo como el parámetro del diccionario personalizado almacenado que volviste a compilar, en formato FieldMask. Por ejemplo, cuando el siguiente JSON se envía al método storedInfoTypes.patch, indica en el parámetro updateMask que se actualizó la URL de la ruta de acceso de Cloud Storage (large_custom_dictionary.cloud_storage_file_set.url):

PATCH https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/storedInfoTypes/github-usernames?key={YOUR_API_KEY}

{
  "config":{
    "largeCustomDictionary":{
      "cloudStorageFileSet":{
        "url":"gs://[BUCKET_NAME]/[PATH_TO_FILE]"
      }
    }
  },
  "updateMask":"large_custom_dictionary.cloud_storage_file_set.url"
}

Analiza contenido con detectores de diccionarios personalizados almacenados

Analizar contenido mediante un detector de diccionario personalizado almacenado es similar a analizar contenido con otro detector de Infotipo personalizado.

Console

Puedes usar un detector de diccionario personalizado cuando creas un nuevo trabajo, activador de trabajo o plantilla. En la sección Configurar detección del flujo de trabajo de creación de plantillas o trabajos, puedes especificar tu Infotipo personalizado de diccionario almacenado en la subsección Infotipos personalizados:

  1. Haz clic en Add custom infoType (Agregar Infotipo personalizado) y, luego, en Stored infoType (Infotipo almacenado).

    Captura de pantalla del flujo de trabajo del activador de creación de trabajos de la IU de DLP, en la sección Infotipos personalizados.

  2. En la sección Add custom infoType (Agregar Infotipo personalizado), escribe un nombre de Infotipo en el campo InfoType. Puedes usar letras, números y guiones bajos.

  3. Haz clic en el campo Stored infoType name (Nombre de Infotipo almacenado). Aparecerá un menú debajo del campo con las rutas de acceso a tus Infotipos personalizados de diccionario almacenado, como se muestra a continuación:

    Captura de pantalla del flujo de trabajo del activador de creación de trabajos de la IU de DLP, en la sección Agregar Infotipo personalizado.

  4. Elige el diccionario personalizado almacenado que desees y, luego, haz clic en Done (Listo).

El Infotipo personalizado que agregaste aparece como en la siguiente captura de pantalla. Ten en cuenta que puedes agregar Infotipos personalizados adicionales si lo deseas.

Captura de pantalla del flujo de trabajo del activador de creación de trabajos de la IU de DLP, con el Infotipo personalizado agregado.

Ahora puedes continuar con el proceso de creación del trabajo, el activador del trabajo o la plantilla.

Protocolo

Cuando el siguiente JSON se envía al método content.inspect, analiza el fragmento de texto dado con el detector de diccionario personalizado almacenado especificado. Ten en cuenta que el parámetro infoType es obligatorio porque todos los Infotipos personalizados, incluidos los diccionarios personalizados almacenados, deben tener un nombre que no entre en conflicto con Infotipos integrados u otros Infotipos personalizados. El parámetro storedType contiene la ruta de acceso del recurso completa del Infotipo personalizado almacenado.

Entrada de JSON:

POST https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/content:inspect?key={YOUR_API_KEY}

{
  "inspectConfig":{
    "customInfoTypes":[
      {
        "infoType":{
          "name":"GITHUB_LOGINS"
        },
        "storedType":{
          "name":"projects/[PROJECT_ID]/storedInfoTypes/github-logins"
        }
      }
    ]
  },
  "item":{
    "value":"The commit was made by githubuser."
  }
}

Soluciona errores

Si, cuando intentas crear un diccionario personalizado almacenado, ves un error que explica que Cloud DLP no puede crear un diccionario a partir de tu lista de términos basada en Cloud Storage, existen algunas causas posibles:

  • Alcanzaste el límite superior para los diccionarios personalizados almacenados. Según el problema, hay varias soluciones:
    • Si alcanzas el límite superior para un único diccionario personalizado almacenado en Cloud Storage (200 MB), puedes intentar dividir el archivo en varios archivos. Aun así, puedes usar estos archivos para ensamblar un único diccionario personalizado, siempre que el tamaño total de los archivos no exceda el tamaño máximo combinado para todos los archivos de diccionarios personalizados almacenados en Cloud Storage (1 GB).
    • BigQuery no tiene los mismos límites que Cloud Storage. Considera mover los términos a una tabla de BigQuery, pero ten en cuenta el tamaño máximo de la columna del diccionario personalizado en BigQuery (1 GB) y la cantidad máxima de filas (5,000,000).
    • Si tu archivo de lista de términos excede todos los límites aplicables para las listas de términos de origen del diccionario personalizado, debes dividir el archivo de la lista de términos en varios archivos en Cloud Storage, crear un diccionario para cada archivo y, luego, crear un trabajo de análisis separado para cada diccionario.
  • Uno o más de tus términos no contienen, al menos, una letra o número. Cloud DLP no puede analizar términos que estén compuestos solo de espacios o símbolos. Debe tener al menos una letra o número. Mira tu lista de términos y fíjate si hay alguno de esos términos incluido y, luego, corrígelo o bórralo.
  • Tu lista de términos contiene una frase con demasiados “componentes”. Un componente en este contexto es una secuencia continua que contiene solo letras, solo números o solo caracteres que no son letras ni dígitos, como espacios o símbolos. Mira tu lista de términos y fíjate si hay alguno de esos términos incluido y, luego, corrígelo o bórralo.
  • La cuenta de servicio DLP no tiene acceso a los datos de origen del diccionario ni al depósito de Cloud Storage para almacenar archivos de diccionario. Para solucionar este problema, otorga a la cuenta de servicio de DLP la función de administrador de Cloud Storage o las funciones de dataOwner y jobUser de BigQuery.

Descripción general de la API

Un diccionario personalizado almacenado se considera un Infotipo almacenado debido a su tamaño y complejidad. En este momento, los diccionarios personalizados almacenados son el único tipo de Infotipo almacenado.

Un Infotipo almacenado se representa en Cloud DLP con el objeto StoredInfoType. Se acompaña de los siguientes objetos relacionados:

  • StoredInfoTypeConfig contiene la configuración del Infotipo almacenado, que incluye detalles como el nombre y la descripción.
  • StoredInfoTypeVersion contiene más información sobre el Infotipo almacenado, como su fecha y hora de creación, y los últimos cinco mensajes de error que se produjeron cuando se creó la versión actual del Infotipo almacenado.
  • StoredInfoTypeState contiene el estado de la versión más reciente y cualquier versión pendiente del Infotipo almacenado. La información de estado incluye si el Infotipo almacenado se está recopilando de nuevo, si está listo para usar o si no es válido.

Para crear, editar o borrar un Infotipo almacenado, utiliza los siguientes métodos:

  • storedInfoTypes.create: crea un nuevo Infotipo almacenado según el objeto StoredInfoTypeConfig que especifiques.
  • storedInfoTypes.patch: vuelve a compilar el Infotipo almacenado con un objeto StoredInfoTypeConfig nuevo o, si no se especifica ninguno, crea una versión nueva del Infotipo almacenado con el objeto StoredInfoTypeConfig existente.
  • storedInfoTypes.get: recupera el objeto StoredInfoTypeConfig y las versiones pendientes del Infotipo almacenado especificado.
  • storedInfoTypes.list: enumera todos los Infotipos almacenados actualmente.
  • storedInfoTypes.delete: borra el Infotipo almacenado especificado.

Además de las API de Infotipo almacenado que se describen aquí, el siguiente objeto se aplica de manera específica a los diccionarios personalizados almacenados:

  • LargeCustomDictionaryConfig especifica lo siguiente:
    • Dónde se almacena tu lista de frases dentro de Cloud Storage o BigQuery.
    • Dónde se almacenan los archivos de diccionario generados en Cloud Storage.

Detalles de coincidencias en el diccionario

A continuación, se presenta una guía sobre cómo Cloud DLP detecta coincidencias entre palabras y frases del diccionario. Estos puntos se aplican a los diccionarios personalizados normales y almacenados:

  • Las palabras del diccionario distinguen entre mayúsculas y minúsculas. Si tu diccionario incluye Abby, coincidirá con abby, ABBY, Abby, etcétera.
  • Todos los caracteres, en los diccionarios o en el contenido que se va a analizar, excepto las letras y los dígitos en el plano multilingüe básico de Unicode, se consideran como espacios en blanco cuando se analizan coincidencias. Si tu diccionario analiza Abby Abernathy, coincidirá con abby abernathy, Abby, Abernathy, Abby (ABERNATHY), etcétera.
  • Los caracteres que rodean cualquier coincidencia deben ser de un tipo diferente (letras o dígitos) de los caracteres adyacentes dentro de la palabra. Si tu diccionario analiza Abi, coincidirá con los tres primeros caracteres de Abi904, pero no de Abigail.
  • Las palabras del diccionario que contienen una gran cantidad de caracteres que no son letras ni dígitos pueden generar resultados inesperados, ya que esos caracteres se tratan como espacios en blanco.