Esta página se ha traducido con Cloud Translation API.

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.

Información general

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

Puedes usar filtros de prefijo de tres formas:

Incluir prefijos: solo se transfieren los objetos que coincidan con los prefijos especificados.
Excluir prefijos: los objetos que coincidan con los prefijos especificados se omitirán de la transferencia.
Ambos a la vez: puedes usar los prefijos de inclusión y exclusión simultáneamente para tener un control más detallado. Cuando se usan juntos, todos los prefijos de exclusión deben empezar por uno de los prefijos de inclusión especificados.

Si no especifica ningún prefijo, se transferirán todos los objetos del contenedor de origen.

Reglas

Los prefijos se rigen por las siguientes reglas:

Sin barras inclinadas iniciales: no incluyas una barra inclinada inicial en un prefijo. En el caso de 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.
En relación con la carpeta de origen: si la fuente de transferencia es una carpeta específica, los prefijos se evalúan en relación con esa carpeta. En el caso de una fuente de gs://my-bucket/data/, un prefijo de inclusión reports coincide con todos los archivos de 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 incluidos.
Excluir dependencia de prefijo: cuando se usan prefijos de inclusión y exclusión juntos, todos los prefijos de exclusión deben empezar por 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 1000 prefijos: un solo trabajo de transferencia admite hasta 1000 prefijos. Puedes dividir una transferencia en varios trabajos si necesitas prefijos adicionales.

Para obtener información más general sobre los prefijos, consulta Listar claves de forma jerárquica mediante un prefijo y un delimitador en la documentación de Amazon S3 o el método list de objetos de Cloud Storage.

Cómo especificar prefijos

consola de Cloud

Para especificar prefijos de inclusión y exclusión mediante la consola de Google Cloud, introduce los valores al crear una transferencia o al actualizar una transferencia.

CLI de gcloud

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, sin dejar espacios después de las comas. Por ejemplo, --include-prefixes="foo,bar".

REST

Para especificar prefijos de inclusión y exclusión mediante la API 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 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

Usar prefijos de inclusión

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

path_1/

Esto incluye los objetos de path_1/. En la transferencia se incluyen 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

Puedes especificar varias rutas para incluirlas. 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 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

Si usas prefijos de inclusión, las rutas que no incluyas específicamente no se transferirán al segmento de destino de Cloud Storage.

Excluir prefijos

Si usa prefijos de exclusión al crear una transferencia, indica al Servicio de transferencia de Storage que ignore las rutas indicadas en la transferencia.

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

path_1/

Esto excluye los objetos de path_1/. En este caso, en la transferencia se incluyen 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

Puedes especificar varias rutas que quieras 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

Incluir y excluir rutas simultáneamente

Puedes aplicar un prefijo de exclusión y un prefijo de inclusión al mismo tiempo. En ese caso, el prefijo de exclusión limita lo que incluye el prefijo de inclusión en la transferencia.

Cuando se especifican ambos tipos de prefijo, cada prefijo de exclusión debe empezar por una ruta que se haya especificado en un prefijo de inclusión.

Por ejemplo, para incluir objetos de path_1/ y excluir objetos de 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 de path_1/ y path_2/, excepto los elementos de 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 habituales que se deben evitar

A continuación, se muestran ejemplos de configuraciones incorrectas y cómo corregirlas.

Incluir una ruta que se usa en otro prefijo include

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

Incorrecto: la ruta de prefijo path_1/subpath_1 ya está cubierta 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 ningún prefijo de inclusión

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

Incorrecto: el prefijo subpath_1 no empieza por path_1/ ni por path_2/.

include: path_1/
         path_2/
exclude: subpath_1

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

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