Filtra objetos de origen por prefijo

En esta guía, se explica cómo usar prefijos de inclusión y exclusión para controlar qué archivos se transfieren.

Descripción general

El Servicio de transferencia de almacenamiento admite el filtrado de datos de Amazon S3, Microsoft Azure Blob Storage y fuentes de Cloud Storage con prefijos. Un prefijo es una cadena de caracteres al principio de una ruta de acceso que especifica un conjunto de objetos.

Puedes usar los filtros de prefijo de tres maneras:

  • Incluir prefijos: Solo se transfieren los objetos que coinciden con los prefijos especificados.

  • Excluir prefijos: Los objetos que coinciden con los prefijos especificados se omiten de la transferencia.

  • Ambos juntos: Puedes usar prefijos de inclusión y exclusión de forma simultánea para obtener un control más detallado. Cuando se usan juntos, cada prefijo de exclusión debe comenzar con uno de los prefijos de inclusión especificados.

Si no especificas ningún prefijo, se transfieren todos los objetos del bucket de origen.

Los filtros de prefijo se pueden combinar con patrones de glob, filtros de hora de última modificación y filtros de clase de almacenamiento de S3.

Reglas

Se aplican las siguientes reglas a los prefijos:

  • Sin barras diagonales iniciales: No incluyas una barra diagonal inicial en un prefijo. Para la ruta s3://my-bucket/logs/2025/requests.gz, el prefijo correcto es logs/2025/requests.gz.

  • Coincidencias parciales: Los prefijos funcionan por coincidencia parcial. Por ejemplo, el prefijo path coincide con path_1/ y path_2/.

  • Sin comodines: No se admiten comodines.

  • Relativo a la carpeta de origen: Si tu fuente de transferencia incluye una ruta de acceso o una carpeta, los prefijos son relativos a esa ruta de acceso o carpeta. Consulta Interacción con la ruta de acceso o la carpeta de origen para obtener más detalles.

  • Prefijos distintos: Cada prefijo de inclusión debe definir una parte única del espacio de nombres del objeto. No puedes usar un prefijo de inclusión que ya esté cubierto por otro prefijo de inclusión. Por ejemplo, no puedes especificar data/ y data/reports/ como prefijos de inclusión. La misma regla se aplica entre los prefijos de exclusión.

  • Dependencia de prefijo de exclusión: Cuando se usan prefijos de inclusión y exclusión juntos, cada prefijo de exclusión debe comenzar con uno de los prefijos de inclusión especificados. Por ejemplo, si path es un prefijo de inclusión, los prefijos de exclusión válidos podrían ser path/b o pathway. Esta regla no se aplica si solo usas prefijos de exclusión.

  • Máximo de 1,000 prefijos de cada tipo: Un solo trabajo de transferencia admite hasta 1,000 prefijos de inclusión y hasta 1,000 prefijos de exclusión. Puedes dividir una transferencia en varios trabajos si se requieren prefijos adicionales.

Para obtener más información general sobre prefijos, consulta Enumera las claves en orden jerárquico con un prefijo y un delimitador en la documentación de Amazon S3 o en el método de enumeración de objetos de Cloud Storage.

Interacción con otros tipos de filtros

Cuando usas varios filtros, el Servicio de transferencia de almacenamiento los aplica en el siguiente orden:

  1. Incluir prefijos: Reduce los objetos que se deben considerar.
  2. Condiciones del objeto (patrón glob, hora de la última modificación y clase de almacenamiento de S3): Filtra los objetos que coinciden con el prefijo de inclusión. Un objeto debe coincidir con todas las condiciones de objeto especificadas para incluirse en la transferencia.
  3. Excluir prefijos: Quita objetos del resultado.

Obtén más información para filtrar con patrones glob, hora de última modificación y clase de almacenamiento de S3.

Interacción con la ruta de acceso o la carpeta de origen

Los filtros de inclusión y exclusión son relativos a cualquier ruta de acceso o carpeta que especifiques para la fuente.

Por ejemplo, si tu fuente es gs://bucketA/alpha y quieres especificar un filtro para gs://bucketA/alpha/beta, haz lo siguiente:

Correcto

  • Ruta de acceso de origen: gs://bucketA/alpha
  • Prefijo de exclusión: beta/
  • Resultado: Se excluye correctamente gs://bucketA/alpha/beta

Incorrecto

  • Ruta de acceso de origen: gs://bucketA/alpha
  • Prefijo de exclusión: alpha/beta/
  • Resultado: Esto define de forma incorrecta un filtro para gs://bucketA/alpha/alpha/beta

Especifica prefijos

Consola de Google Cloud

Para especificar los prefijos de inclusión y exclusión con la consola deGoogle Cloud , ingresa los valores cuando crees una transferencia nueva o cuando actualices una transferencia existente.

gcloud CLI

Para especificar los prefijos de inclusión y exclusión con la CLI de gcloud, pasa las marcas --include-prefixes y --exclude-prefixes al comando gcloud transfer jobs create o al comando gcloud transfer jobs update:

gcloud transfer jobs create SOURCE DESTINATION \
  --include-prefixes="path_1/,path_2/" --exclude-prefixes="path_1/subpath_2/"

Separa varios prefijos con comas, sin dejar espacios después de las comas. Por ejemplo, --include-prefixes="foo,bar".

REST

Para especificar los prefijos de inclusión y exclusión con la API de REST, usa los campos includePrefixes[] y excludePrefixes[]:

{
    "description": "Transfer with prefixes",
    "status": "ENABLED",
    "projectId": "PROJECT_ID",
    "schedule": {
        "scheduleStartDate": {
            "day": 1,
            "month": 1,
            "year": 2015
        },
        "startTimeOfDay": {
            "hours": 1,
            "minutes": 1
        }
    },
    "transferSpec": {
        "gcsDataSource": {
            "bucketName": "SOURCE_BUCKET"
        },
        "gcsDataSink": {
            "bucketName": "DESTINATION_BUCKET"
        },
        "transferOptions": {
            "deleteObjectsFromSourceAfterTransfer": true
        },
        "objectConditions": {
            "includePrefixes": [
                "path_1/",
                "path_2/"
            ],
            "excludePrefixes": [
                "path_1/subpath_2/object_5"
            ]
        }
    }
}

Para obtener más información, consulta la referencia de ObjectConditions.

Ejemplos de objetos y rutas

En los siguientes ejemplos, se usa esta lista de objetos de muestra:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Usa prefijos de inclusión

Para transferir solo los objetos que se encuentran en path_1/, usa el siguiente prefijo:

path_1/

Esto incluye los objetos que se encuentran en path_1/. Los siguientes objetos se incluyen en la transferencia:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Puedes especificar varias rutas de acceso para incluir. Por ejemplo, puedes pasar lo siguiente:

path_1/subpath_2/
path_2/subpath_3/

En este caso, la transferencia incluye los siguientes objetos:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Se admiten las coincidencias parciales. Por ejemplo:

path

Se transfieren los siguientes objetos:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Cuando usas prefijos de inclusión, las rutas de acceso que no incluyes de forma específica no se transfieren al bucket de destino de Cloud Storage.

Excluye prefijos

Cuando usas prefijos de exclusión para crear una transferencia, el Servicio de transferencia de almacenamiento ignora las rutas de acceso de la lista para la transferencia.

Para excluir objetos en path_1/, pasa el siguiente prefijo:

path_1/

Esto excluye los objetos que se encuentran en path_1/. En este caso, se incluyen los siguientes objetos en la transferencia:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Puedes especificar varias rutas de acceso para excluir. Por ejemplo, puedes pasar lo siguiente:

path_1/subpath_2/
path_2/subpath_3/

En este caso, la transferencia incluye los siguientes objetos:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Incluye y excluye rutas de acceso de manera simultánea

Puedes aplicar un prefijo de exclusión y un prefijo de inclusión juntos, en cuyo caso el prefijo de exclusión limita lo que el prefijo de inclusión incluye en la transferencia.

Cuando se especifican ambos tipos de prefijo, cada prefijo de exclusión debe comenzar con una ruta de acceso que se especifica en un prefijo de inclusión.

Por ejemplo, para incluir objetos en path_1/ y excluir objetos en subpath_1/, pasa lo siguiente:

include: path_1/
exclude: path_1/subpath_1/

En este caso, la transferencia incluye los siguientes objetos:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Para incluir todos los objetos en path_1/ y path_2/, excepto los elementos en path_1/subpath_1/ o path_2/subpath_3/, pasa lo siguiente:

include: path_1/
         path_2/
exclude: path_1/subpath_1/
         path_2/subpath_3/

En este caso, la transferencia incluye los siguientes objetos:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Errores comunes que se deben evitar

A continuación, se muestran ejemplos de parámetros de configuración incorrectos y cómo corregirlos.

Incluir una ruta de acceso que se usa en otro prefijo de inclusión

Un prefijo de inclusión no puede ser un subdirectorio de otro prefijo de inclusión.

Incorrecto: El prefijo path_1/subpath_1 ya está cubierto por path_1/.

include: path_1/
         path_1/subpath_1

Correcto: Para solucionar este problema, quita el prefijo redundante y más específico.

include: path_1/

El prefijo de exclusión no coincide con un prefijo de inclusión

Cuando se usan juntos, un prefijo de exclusión debe comenzar con uno de los prefijos de inclusión.

Incorrecto: El prefijo subpath_1 no comienza con path_1/ ni con path_2/.

include: path_1/
         path_2/
exclude: subpath_1

Correcto: Asegúrate de que el prefijo de exclusión contenga la ruta de acceso completa de un prefijo de inclusión.

include: path_1/
         path_2/
exclude: path_1/subpath_1/