À propos des objets Cloud Storage

Cette page décrit les objets, qui sont une ressource dans Cloud Storage. Pour obtenir une présentation générale du fonctionnement de Cloud Storage, consultez la page Présentation du produit Cloud Storage.

Objets

Les objets sont des données individuelles stockées dans Cloud Storage. Vous pouvez créer autant d'objets que vous le souhaitez dans un bucket.

Les objets se composent de deux éléments : les données d'objets et les métadonnées d'objets. Les données d'objets correspondent généralement des fichiers que vous souhaitez stocker dans Cloud Storage. Elles sont totalement opaques pour Cloud Storage. Les métadonnées d'objets correspondent à un ensemble de paires nom/valeur décrivant diverses propriétés des objets.

Le nom d'objet et son numéro de génération sont deux métadonnées importantes communes à tous les objets. Lorsque vous ajoutez un objet à un bucket Cloud Storage, vous spécifiez son nom et Cloud Storage attribue le numéro de génération. Ensemble, le nom et la génération identifient de manière unique l'objet dans ce bucket.

Vous pouvez utiliser des listes de contrôle d'accès (LCA) pour contrôler l'accès à des objets individuels. Vous pouvez également utiliser Identity and Access Management (IAM) pour contrôler l'accès à tous les objets d'un bucket ou d'un dossier géré.

Considérations relatives aux noms

Le nom que vous attribuez à un objet doit répondre aux exigences suivantes :

  • Les noms d’objet peuvent contenir n'importe quelle séquence de caractères Unicode valides, d'une longueur comprise entre 1 et 1 024 octets pour l'encodage en UTF-8.
  • Les noms d'objet ne peuvent pas contenir de caractères de retour chariot ni de saut de ligne.
  • Les noms d'objets ne peuvent pas commencer par .well-known/acme-challenge/.
  • Les objets ne peuvent pas être nommés . ou ...

Il est vivement recommandé d'éviter d'intégrer les éléments suivants dans les noms d'objet :

  • Les caractères de contrôle illégaux dans XML 1.0 (#x7F–#x84 et #x86–#x9F) : ces caractères entraînent des problèmes de liste XML lorsque vous tentez de répertorier vos objets.
  • Le caractère # : les commandes de Google Cloud CLI interprètent les noms d'objet se terminant par #<chaîne numérique> comme des identifiants de version. Par conséquent, l'inclusion de # dans les noms d'objet peut rendre difficile ou impossible d'effectuer des opérations sur ces objets avec des versions gérées à l'aide de gcloud CLI.
  • Les caractères [, ], * ou ? : les commandes de Google Cloud CLI interprètent ces caractères comme des caractères génériques. Par conséquent, leur inclusion dans les noms d'objet peut rendre difficile, voire impossible, l'exécution d'opérations génériques. De plus, * et ? ne sont pas des caractères valides pour les noms de fichiers sous Windows.
  • Les caractères :, ", <, > ou | : il ne s'agit pas de caractères valides pour les noms de fichiers sous Windows. Par conséquent, le téléchargement d'un objet contenant ces caractères dans son nom vers un fichier Windows échoue, sauf si la méthode de téléchargement inclut le changement de nom du fichier Windows obtenu. Le caractère /, même s'il ne s'agit pas d'un caractère valide pour les noms de fichiers sous Windows, peut généralement être utilisé dans les noms d'objet pour imiter une structure de répertoires. Les outils tels que Google Cloud CLI convertissent automatiquement le caractère en \ lors du téléchargement dans un environnement Windows.
  • Informations sensibles ou personnelles : les noms d'objet sont davantage visibles que les données d'objet. Par exemple, les noms d'objet s'affichent dans les URL des objets ou des listes d'objets d'un bucket.

Les objets existants ne peuvent pas être renommés directement, mais vous pouvez renommer indirectement un objet en copiant et en supprimant l'objet d'origine.

Espace de noms d'objet

Les noms d'objet se trouvent dans un espace de noms unique au sein d'un bucket. Cela signifie que :

  • Différents buckets peuvent comporter des objets portant le même nom.
  • Les objets ne se trouvent pas dans des sous-répertoires d'un bucket.

Par commodité, il existe plusieurs façons de traiter les objets comme s'ils étaient stockés dans une hiérarchie de dossiers :

Par exemple, si vous créez un objet nommé folder1/file.txt dans le bucket your-bucket, le chemin d'accès à l'objet est your-bucket/folder1/file.txt, mais Cloud Storage n'a pas de dossier nommé folder1 hébergé dans ce bucket. Du point de vue de Cloud Storage, la chaîne folder1/ fait partie du nom de l'objet.

Cependant, comme le nom de l'objet comporte un /, certains outils mettent en œuvre une simulation de dossiers. Par exemple, si vous utilisez la console Google Cloud, vous accédez à l'objet folder1/file1.txt comme s'il s'agissait d'un objet nomméfile1.txt dans un dossier nommé folder1. De même, vous pouvez créer un dossier géré nommé folder1, puis file1.txt sera soumis à la stratégie d'accès définie par ce dossier géré.

Notez que, comme les objets résident dans un espace de noms plat, les structures de type répertoires profondément imbriqués n'offrent pas les mêmes performances qu'un système de fichiers natif répertoriant des sous-répertoires profondément imbriqués.

Consultez la section Bonnes pratiques concernant le taux de requêtes pour savoir comment optimiser les performances en évitant les noms séquentiels lors des importations à grande échelle. Les objets importés avec des noms séquentiels sont susceptibles d'atteindre le même serveur backend et de limiter les performances.

Dossiers simulés

Pour vous aider à organiser des objets dans vos buckets Cloud Storage, certains outils simulent des dossiers, et les API JSON et XML disposent toutes deux de fonctionnalités vous permettant de concevoir votre propre schéma de nommage pour simuler des dossiers. Cliquez sur les onglets suivants pour voir comment différents outils gèrent les dossiers simulés.

Console

La console Google Cloud crée une représentation visuelle des dossiers qui ressemblent à l'explorateur de fichiers local.

Dans la console Google Cloud, vous pouvez créer un dossier vide dans un bucket ou importer un dossier existant.

Lorsque vous importez un dossier existant, le nom du dossier devient une partie du chemin d'accès à tous les objets qu'il contient. Tous les sous-dossiers et les objets qu'ils contiennent sont également inclus dans l'importation.

Pour créer un dossier, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page du Navigateur Cloud Storage.

    Accéder à la page "Buckets"

  2. Accédez au bucket.

  3. Cliquez sur Créer un dossier pour créer un dossier vide ou sur Importer un dossier pour importer un dossier existant.

Ligne de commande

Les CLI Cloud Storage simulent l'expérience de répertoire de ligne de commande classique à l'aide de diverses règles.

Afin de simuler l'arborescence de fichiers hiérarchique, gcloud CLI applique les règles suivantes pour déterminer si l'URL de destination d'une commande doit être traitée comme un nom d'objet ou un dossier :

  1. Si l'URL de destination se termine par le caractère /, les commandes de gcloud CLI traitent l'URL de destination comme un dossier. Prenons l'exemple de la commande suivante, où your-file est le nom d'un fichier :

    gcloud storage cp your-file gs://your-bucket/abc/

    Suite à cette commande, Cloud Storage crée un objet nommé abc/your-file dans le bucket your-bucket.

  2. Si vous copiez plusieurs fichiers sources dans une URL de destination, soit à l'aide de l'option --recursive, soit à l'aide d'un caractère générique tel que **, la CLI gcloud traite l'URL de destination comme un dossier. Par exemple, considérons la commande suivante, où top-dir est un dossier contenant des fichiers tels que file1 et file2 :

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    À la suite de cette commande, Cloud Storage crée les objets abc/top-dir/file1 et abc/top-dir/file2 dans le bucket your-bucket.

  3. Si aucune de ces règles ne s'applique, gcloud CLI vérifie les objets du bucket pour déterminer si l'URL de destination est un nom d'objet ou un dossier. Prenons l'exemple de la commande suivante, où your-file est le nom d'un fichier :

    gcloud storage cp your-file gs://your-bucket/abc

    gcloud CLI envoie une requête de liste d'objets pour your-bucket, en utilisant le délimiteur / et le préfixe abc, afin de déterminer s'il existe des objets dans your-bucket dont le chemin d'accès commence par abc/. Si c'est le cas, gcloud CLI traite abc/ comme un nom de dossier et la commande crée l'objet abc/your-file dans le bucket your-bucket. Sinon, gcloud CLI crée l'objet abc dans your-bucket.

Cette approche basée sur des règles diffère du fonctionnement de nombreux outils, qui créent des objets de 0 octet pour marquer l'existence de dossiers. gcloud CLI comprend plusieurs conventions utilisées par ces outils, telles que l'ajout de _$folder$ à la fin du nom de l'objet de 0 octet, mais cela ne nécessite pas ces objets repère pour mettre en œuvre un comportement de dénomination cohérent avec les commandes UNIX.

Outre ces règles, la manière dont gcloud CLI traite les fichiers sources varie selon que vous utilisez ou non l'option --recursive. Si vous utilisez l'option, gcloud CLI crée des noms d'objets pour refléter la structure du répertoire source, en commençant par le point de traitement récursif. Par exemple, considérons la commande suivante, où home/top-dir est un dossier contenant des fichiers tels que file1 et sub-dir/file2 :

gcloud storage cp home/top-dir gs://your-bucket --recursive

À la suite de cette commande, Cloud Storage crée les objets top-dir/file1 et top-dir/sub-dir/file2 dans le bucket your-bucket.

En revanche, si vous effectuez une copie sans l'option --recursive, même si plusieurs fichiers sont copiés en raison de la présence d'un caractère générique tel que **, vous obtenez des objets nommés par le composant de chemin final des fichiers sources. Par exemple, en supposant à nouveau que home/top-dir est un dossier contenant des fichiers tels que file1 et sub-dir/file2, la commande suivante :

gcloud storage cp home/top-dir/** gs://your-bucket

crée un objet nommé file1 et un objet nommé file2 dans le bucket your-bucket.

Nouvelles tentatives et dénomination

Quand gcloud CLI relance une requête interrompue, vous risquez de rencontrer un problème dans lequel la première tentative copie un sous-ensemble de fichiers et les tentatives suivantes rencontrent un dossier de destination déjà existant, ce qui entraîne un nom incorrect de vos objets.

Prenons l'exemple de la commande suivante, qui comporte des sous-dossiers sous your-dir/, tels que dir1 et dir2, et où les deux sous-dossiers contiennent le fichier abc :

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

Si le chemin d'accès gs://your-bucket/new n'existe pas encore, gcloud CLI crée les objets suivants à la première tentative réussie :

new/dir1/abc
new/dir2/abc

Toutefois, à la prochaine tentative réussie de la même commande, gcloud CLI crée les objets suivants :

new/your-dir/dir1/abc
new/your-dir/dir2/abc

Pour que gcloud CLI fonctionne de manière cohérente à chaque tentative, procédez comme suit :

  1. Ajoutez une barre oblique à la fin de l'URL de destination pour que gcloud CLI la traite toujours comme un dossier.

  2. Utilisez gcloud storage rsync. Étant donné que rsync n'utilise pas les règles de dénomination des dossiers définies par cp d'Unix, la commande s'exécute de manière cohérente, que le sous-dossier de destination existe ou non.

Remarques supplémentaires

  • Vous ne pouvez pas créer un objet de zéro octet pour imiter un dossier vide à l'aide de gcloud CLI.

  • Lors du téléchargement vers un système de fichiers local, gcloud CLI ignore les objets dont le nom se termine par le caractère /, car la création d'un fichier se terminant par / n'est pas autorisée sous Linux et macOS.

  • Si vous utilisez des scripts pour créer des chemins de fichiers en combinant des sous-chemins, notez que comme / est simplement un caractère qui se trouve dans le nom de l'objet, les CLI interprètent gs://your-bucket/folder/ comme un objet différent de gs://your-bucket//folder.

API REST

API JSON

Les dossiers n'existent pas dans l'API JSON. Vous pouvez affiner les objets que vous répertoriez et simuler des dossiers en utilisant les paramètres de requête prefix et delimiter.

Par exemple, pour répertorier tous les objets du bucket my-bucket avec le préfixe folder/subfolder/, exécutez une requête de liste d'objets en utilisant cette URL :

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

API XML

Les dossiers n'existent pas dans l'API XML, mais vous pouvez affiner les objets que vous répertoriez et simuler des dossiers à l'aide des paramètres de requête prefix et delimiter.

Par exemple, pour répertorier tous les objets du bucket my-bucket avec le préfixe folder/subfolder/, exécutez une requête de liste d'objets en utilisant cette URL :

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

Supprimer des dossiers simulés

Comme les dossiers simulés n'existent pas réellement, vous pouvez généralement supprimer les dossiers simulés en renommant les objets de sorte que le dossier simulé ne fasse plus partie du nom de l'objet. Par exemple, si vous disposez d'un objet nommé folder1/file, vous pouvez supprimer le dossier simulé folder1/ en renommant simplement l'objet en file.

Toutefois, si vous avez utilisé un outil qui crée des objets de zéro octet en tant qu'espace réservé au dossier, tel que la console Google Cloud, vous devez supprimer l'objet de zéro octet pour supprimer le dossier.

Immuabilité des objets

Les objets sont immuables, ce qui signifie qu'un objet importé ne peut pas être modifié pendant l'intégralité de sa durée de stockage. La durée de stockage d'un objet est le temps qui s'écoule entre la création d'un objet réussie, telle que l'importation, et sa suppression. En pratique, cela signifie que vous ne pouvez pas apporter de nouvelles modifications aux objets, telles que des opérations d'ajout ou de troncation. Cependant, il est possible de remplacer les objets stockés dans Cloud Storage, ce qui se fait de manière atomique. L'ancienne version de l'objet est transmise aux lecteurs jusqu'à la fin de la nouvelle importation. Ensuite, c'est la nouvelle version qui est distribuée. Une opération de remplacement unique marque la fin de la durée de vie d'un objet immuable, mais également le commencement de celle d'un nouvel objet immuable.

Le numéro de génération d'un objet change chaque fois que vous remplacez les données de cet objet. Ainsi, le numéro de génération identifie de manière unique un objet immuable.

Notez qu'il existe une limite fixée à une fois par seconde pour le remplacement rapide d'un même objet. Le remplacement du même objet plus d'une fois par seconde peut entraîner des erreurs 429 Too Many Requests. Vous devez concevoir votre application de manière à importer les données d'un objet particulier une fois par seconde au maximum et à gérer les erreurs 429 Too Many Requests occasionnelles à l'aide d'une stratégie d'intervalle exponentiel entre les tentatives.

Étapes suivantes