Filtra por prefijo

En esta página, se muestra cómo incluir y excluir rutas de acceso de transferencias mediante prefijos de inclusión y exclusión.

Para obtener información sobre cómo crear un manifiesto de objetos específicos para transferir, consulta Cómo transferir archivos u objetos específicos con un manifiesto.

Descripción general

El Servicio de transferencia de almacenamiento admite el uso de prefijos para seleccionar qué archivos incluir o excluir de la fuente de datos. Puedes usar prefijos de exclusión, de exclusión o ambos.

El filtrado por prefijo es compatible con las fuentes de datos de Amazon S3, Microsoft Azure Blob Storage y Cloud Storage.

  • No se debe incluir la barra final previa en un prefijo. Por ejemplo, para incluir el objeto requests.gz en una transferencia desde la siguiente ruta de bucket s3://my-aws-bucket/logs/y=2015/requests.gz, especifique el prefijo de inclusión como logs/y=2015/requests.gz.

  • Se admiten coincidencias parciales para los prefijos de inclusión y exclusión. Por ejemplo, path coincide con path_1/ y path_2/.

  • Los comodines no son compatibles.

  • Cada prefijo de inclusión debe incluir una parte distinta del espacio de nombres del objeto. Ningún prefijo de inclusión puede ser un prefijo de otro. Por ejemplo, no puedes especificar path_1 y path_1/subpath_2 como prefijos de inclusión.

  • Si usas prefijos de inclusión y exclusión en conjunto, los de exclusión deben comenzar con el valor de uno de los de inclusión. Por ejemplo, si especificas a como un prefijo de inclusión, los prefijos de exclusión válidos son a/b, aaa y abc.

  • No tienes restricciones sobre los prefijos que puedes usar si usas solo prefijos de exclusión.

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

  • Cuando uses prefijos, no proporciones un nombre de ruta para los nombres de la fuente de datos o el bucket del receptor. Por ejemplo, s3://my-aws-bucket y gs://example-bucket son válidos, pero s3://my-aws-bucket/subfolder o gs://example-bucket/files no lo son. Usa prefijos de inclusión y de exclusión para incluir rutas de acceso.

Para obtener más información general sobre prefijos, consulta Enumera las claves en orden jerárquico mediante 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.

Cómo especificar prefijos

Consola de Cloud

Para especificar los prefijos “Incluir” y “Excluir” con Cloud Console, ingresa los valores cuando crees una transferencia nueva o cuando actualices una transferencia existente.

CLI de gcloud

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

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

Separa los distintos prefijos con comas y omite los espacios después de este. Por ejemplo, --include-prefixes=foo,bar.

REST

Para especificar los prefijos de inclusión y exclusión mediante 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 ejemplos de este documento se usan los siguientes objetos y las siguientes rutas de muestra:

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

Incluir prefijos

Usa prefijos de inclusión cuando crees una transferencia a fin de indicarle al Servicio de transferencia de almacenamiento que considere los objetos en las rutas de acceso enumeradas para la transferencia y que ignore los objetos que no están en esas rutas.

Por ejemplo, para incluir objetos en path_1/, usa el siguiente prefijo:

path_1/

Esto incluye objetos directamente en path_1/, path_1/subpath_1 y path_1/subpath_2/. 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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, si especificas path como el valor de un prefijo de inclusión, se coincidirán con los siguientes objetos:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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 que no incluyes de manera específica no se transfieren al bucket de destino de Cloud Storage.

Excluir prefijos

El uso de prefijos de exclusión cuando se crea una transferencia le indica al Servicio de transferencia de almacenamiento que ignore las rutas de acceso enumeradas para la transferencia.

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

path_1/

Esto excluye los objetos en path_1/, path_1/subpath_1/ y path_1/subpath_2/. 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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 excluirlas. 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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 junto con uno de inclusión, 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 prefijos, cada prefijo de exclusión debe comenzar con una ruta 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Ejemplos de inclusión o exclusión incorrecta de las rutas de acceso

En las siguientes secciones, se incluyen ejemplos que se deben evitar cuando se usan rutas de inclusión o exclusión y se indica cómo corregirlas para que funcionen correctamente.

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

Cada prefijo de inclusión debe especificar una parte distinta del espacio de nombres del objeto. El siguiente ejemplo es incorrecto, ya que el segundo valor está incluido en el espacio de nombres del primer valor:

include: path_1/
         path_1/subpath_1

En este ejemplo, los valores de prefijo de inclusión no son válidos porque el segundo prefijo de inclusión, path_1/subpath_1, ya está incluido en path_1/. Para solucionar este problema, quite uno de los valores.

Usar un prefijo de exclusión que no comience con un prefijo de inclusión

Cada prefijo de exclusión debe comenzar con cualquiera de los valores de prefijo de inclusión especificados. El siguiente ejemplo es incorrecto porque los valores de prefijo de exclusión no comienzan con los valores de prefijo de inclusión especificados:

include: path_1/
         path_2/
exclude: subpath_1
         subpath_4

En este ejemplo, los valores de prefijo de exclusión no son válidos porque no comienzan con ninguno de los valores de prefijo de inclusión. Para solucionar este problema, asegúrate de que el prefijo de exclusión incluya una ruta completa que aparezca como un prefijo de inclusión:

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

¿Qué sigue?