Se usó la API de Cloud Translation para traducir esta página.

Filtrar por prefijo

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

Descripción general

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

Puedes usar 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 tener un control más detallado. Cuando se usan en conjunto, cada prefijo de exclusión debe comenzar con uno de los prefijos de inclusión especificados.

Si no especificas prefijos, se transferirán todos los objetos que estén en el bucket de origen.

Reglas

Se aplican las siguientes reglas a los prefijos:

Sin barras iniciales: No incluyas una barra inicial en un prefijo. Para la ruta de acceso s3://my-bucket/logs/2025/requests.gz, el prefijo correcto es logs/2025/requests.gz.
Coincidencias parciales: Los prefijos funcionan con coincidencias parciales. 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 es una carpeta específica, los prefijos se evalúan en relación con esa carpeta. Para una fuente de gs://my-bucket/data/, un prefijo de inclusión de reports coincide con todos los archivos en gs://my-bucket/data/reports.
Prefijos de inclusión 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.
Dependencia del 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: Un solo trabajo de transferencia admite hasta 1,000 prefijos. 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 el método de lista de objetos de Cloud Storage.

Cómo especificar prefijos

Consola de Cloud

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

gcloud CLI

Para especificar 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 y omite los espacios después de las comas. Por ejemplo, --include-prefixes="foo,bar".

REST

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

{
    "description": "YOUR DESCRIPTION",
    "status": "ENABLED",
    "projectId": "PROJECT_ID",
    "schedule": {
        "scheduleStartDate": {
            "day": 1,
            "month": 1,
            "year": 2015
        },
        "startTimeOfDay": {
            "hours": 1,
            "minutes": 1
        }
    },
    "transferSpec": {
        "gcsDataSource": {
            "bucketName": "GCS_SOURCE_NAME"
        },
        "gcsDataSink": {
            "bucketName": "GCS_SINK_NAME"
        },
        "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 muestra de 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

Usa prefijos de inclusión

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

path_1/

Esto incluye los objetos 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_1/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 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 incluyas de forma específica no se transfieren al bucket de destino de Cloud Storage.

Excluir prefijos

Si usas prefijos de exclusión cuando creas una transferencia, se le indica al Servicio de transferencia de almacenamiento que ignore las rutas enumeradas para la transferencia.

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

path_1/

Esto excluye los objetos 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 especifiques ambos tipos de prefijo, cada prefijo de exclusión debe comenzar con una ruta de acceso que se especifique 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 incluyen ejemplos de configuraciones incorrectas y cómo corregirlas.

Incluye 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: La ruta de acceso path_1/subpath_1 ya está cubierta por path_1/.

include: path_1/
         path_1/subpath_1

Corrección: Para corregir 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 en conjunto, 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/