Comodines de URI

Google Cloud CLI admite el uso de comodines de URI para archivos, buckets y objetos. Los comodines te permiten trabajar de manera eficiente con grupos de archivos que coinciden con patrones de denominación especificados. En esta página, se describen los comodines compatibles y se mencionan consideraciones importantes cuando se usan comodines en los comandos.

Caracteres comodín

gcloud CLI admite los siguientes comodines:

Carácter Descripción
* Coincide con cero o más caracteres dentro del nivel del directorio actual. Por ejemplo, cp gs://my-bucket/abc/d* coincide con el objeto abc/def.txt, pero no con el objeto abc/def/g.txt. En el caso de enumerar comandos como ls, si un * al final coincide con un subdirectorio en el nivel del directorio actual, el contenido del subdirectorio también se enumera.
** Coincide con cero o más caracteres en los límites del directorio. Cuando se usa como parte de la ruta de acceso de un archivo local, el comodín ** siempre debe ir precedido de inmediato por un delimitador de directorio. Por ejemplo, my-directory/**.txt es válido, pero my-directory/abc** no lo es.
? Coincide con un solo carácter. Por ejemplo, gs://bucket/??.txt solo coincide con objetos con dos caracteres seguidos de .txt.
[CHARACTERS] Coincide con cualquiera de los caracteres especificados. Por ejemplo, gs://bucket/[aeiou].txt coincide con los objetos que contienen un solo carácter de vocal seguido de .txt.
[CHARACTER_RANGE] Coincide con cualquiera de los rangos de caracteres. Por ejemplo, gs://bucket/[a-e].txt coincide con los objetos que contienen la letra a, b, c, d o e seguida de .txt.

Puedes combinar comodines para proporcionar coincidencias más eficaces, por ejemplo:

gs://*/[a-m]??.j*g

Ten en cuenta que, a menos que tu comando incluya una marca para mostrar versiones de objetos no actuales en los resultados, estos comodines solo coinciden con las versiones de objetos activas.

gcloud CLI admite los mismos comodines para nombres de objetos y archivos. Por ejemplo:

gcloud storage cp data/abc* gs://bucket

coincide con todos los archivos que comienzan con abc en el directorio data del sistema de archivos local.

Consideraciones de comportamiento

Existen varios casos en los que el uso de comodines puede dar como resultado comportamientos inesperados:

  • Cuando se usan comodines en los nombres de los buckets, las coincidencias se limitan a los buckets en un solo proyecto. Muchos comandos te permiten especificar un proyecto mediante una marca. Si en un comando no se incluye una marca del proyecto o no se admite el uso de una marca del proyecto, las coincidencias se limitan a los buckets en el proyecto predeterminado.

  • Las shells (como bash y zsh) pueden intentar expandir los comodines antes de pasar los argumentos a gcloud CLI. Si el comodín se refería a un objeto en la nube, esto puede generar errores inesperados de “No se encontró”. Por ejemplo, la shell podría intentar expandir el comodín gs://my-bucket/* en la máquina local, lo que no coincidiría con ningún archivo local, lo que provocaría que el comando falle.

    Además, algunas shells incluyen otros caracteres en sus grupos de caracteres comodín. Por ejemplo, si usas zsh con la opción extendedglob habilitada, se tratará a # como un carácter especial, lo que entra en conflicto con el uso de ese carácter para hacer referencia a los objetos con versión (consulta Restaura las versiones de objetos no actuales para obtener un ejemplo).

    Para evitar estos problemas, encierra la expresión de comodín con comillas simples (en Linux) o comillas dobles (en Windows).

  • Intentar especificar un nombre de archivo que contenga caracteres comodín no funcionará, ya que las herramientas de línea de comandos intentan expandir los caracteres comodín en lugar de usarlos como caracteres literales. Por ejemplo:

    gcloud storage cp './file[1]' gs://my-bucket

    nunca copia un archivo local llamado file[1]. En cambio, gcloud CLI siempre trata a [1] como un comodín.

    gcloud CLI no admite un modo “sin procesar” que le permita trabajar con nombres de archivos que contienen caracteres comodín. Para esos archivos, debes usar una herramienta diferente, como la consola de Google Cloud, o usar un comodín a fin de capturar los archivos. Por ejemplo, para capturar un archivo llamado file[1], puedes usar el comando siguiente:

    gcloud storage cp './file*1*' gs://my-bucket
  • Por comportamiento estándar de Unix, el comodín * solo coincide con los archivos que no comienzan con un carácter . (para evitar confusiones con los directorios . y .. presentes en todos los directorios de Unix). gcloud CLI proporciona este mismo comportamiento cuando se usan comodines en un URI del sistema de archivos, pero no proporciona este comportamiento en URI de la nube. Por ejemplo, el siguiente comando copia todos los objetos de gs://bucket1 a gs://bucket2:

    gcloud storage cp gs://bucket1/* gs://bucket2

    Sin embargo, el siguiente comando solo copia los archivos que no comienzan con un . del directorio dir a gs://bucket1:

    gcloud storage cp dir/* gs://bucket1

Consideraciones sobre la eficiencia

  • Es más eficiente, más rápido y requiere menos tráfico de red usar comodines que tengan un prefijo de nombre de objeto sin comodín, como los siguientes:

    gs://bucket/abc*.txt

    Esto se contrapone a usar comodines como la primera parte del nombre del objeto, por ejemplo:

    gs://bucket/*abc.txt

    Esto se debe a que la solicitud de gs://bucket/abc*.txt le pide al servidor que vuelva a enviar el subconjunto de resultados cuyo nombre de objeto comienza con abc en la raíz del bucket y, luego, filtra la lista de resultados para objetos cuyos nombres terminan con .txt. Por el contrario, gs://bucket/*abc.txt solicita al servidor la lista completa de objetos en la raíz del bucket y, luego, filtra los objetos cuyos nombres terminan en abc.txt. Esta consideración de eficiencia se vuelve cada vez más evidente cuando usas buckets que contienen miles de objetos o más. A veces, es posible configurar los nombres de los objetos para que se ajusten a los patrones de coincidencia de comodines esperados, a fin de aprovechar la eficiencia de realizar solicitudes de prefijos del servidor.

  • Supongamos que tienes un bucket con estos objetos:

    gs://bucket/obj1
    gs://bucket/obj2
    gs://bucket/obj3
    gs://bucket/obj4
    gs://bucket/dir1/obj5
    gs://bucket/dir2/obj6

    Si ejecutas el comando a continuación, ocurrirá lo siguiente:

    gcloud storage ls gs://bucket/*/obj5

    gcloud storage genera una lista de buckets de nivel superior delimitada por / y, luego, una lista de buckets para cada subdirectorio, lo que da como resultado un total de 3 listas de buckets:

    GET /bucket/?delimiter=/
    GET /bucket/?prefix=dir1/obj5&delimiter=/
    GET /bucket/?prefix=dir2/obj5&delimiter=/
    

    Cuantas más listas de buckets requiera tu comodín, más lento y costoso será. La cantidad de listas de depósitos necesarias aumenta según lo siguiente:

    • La cantidad de componentes del comodín (p. ej., gs://bucket/a??b/c*/*/d tiene 3 componentes comodín);

    • La cantidad de subdirectorios que coinciden con cada componente

    • La cantidad de resultados (la paginación se implementa cuando la cantidad de resultados es demasiado grande y se especifican los marcadores para cada uno).

    Si deseas usar un comodín de mitad de ruta de acceso, puedes intentar usar un comodín recurrente, por ejemplo:

    gcloud storage ls gs://bucket/**/obj5

    Esto coincidirá con más objetos que gs://bucket/*/obj5 (ya que abarca directorios), pero se implementa mediante una solicitud de lista de buckets sin delimitador (lo que significa una menor cantidad de solicitudes de buckets, a pesar de que enumera todo el bucket y se filtra de forma local, por lo que podría requerir una cantidad no trivial de tráfico de red).