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 eslogs/2025/requests.gz.Coincidencias parciales: Los prefijos funcionan por coincidencia parcial. Por ejemplo, el prefijo
pathcoincide conpath_1/ypath_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/ydata/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
pathes un prefijo de inclusión, los prefijos de exclusión válidos podrían serpath/bopathway. 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:
- Incluir prefijos: Reduce los objetos que se deben considerar.
- 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.
- 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_1xx://bucketname/object_2xx://bucketname/path_1/object_3 xx://bucketname/path_1/subpath_1/object_4 xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
Se admiten las coincidencias parciales. Por ejemplo:
path
Se transfieren los siguientes objetos:
xx://bucketname/object_1xx://bucketname/object_2xx://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_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://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_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5 xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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/