Comment configurer ossutil - Object Storage Service - Centre de documentation Alibaba Cloud

Passer à ossutil 2,0

Nous vous recommandons de passer à ossutil 2,0. Pour installer et utiliser rapidement l'outil, consultez la section Installer ossutil.

Voici les principales fonctionnalités d'ossutil 2,0 :

Nouvelle structure de commandes : ossutil 2,0 prend en charge les commandes multiniveaux, notamment les commandes au niveau de l'API telles que ossutil api put-bucket-acl et les commandes de haut niveau telles que ossutil config.
Gestion de la configuration améliorée : Le processus de configuration initiale est simplifié. Après l'installation, configurez les paramètres de base en fournissant uniquement un AccessKey ID, un AccessKey Secret et une région. Vous pouvez également spécifier plusieurs fichiers de configuration à l'aide du paramètre --profile pour plus de flexibilité.
Paramètres de filtrage riches : Les commandes de traitement par lots telles que ls, cp et rm prennent désormais en charge plusieurs conditions de filtrage. Filtrez par chemin, taille de fichier, heure de modification ou métadonnées d'objet pour améliorer la précision et l'efficacité des opérations.
Formats de sortie flexibles : Le nouveau paramètre --output-format vous permet de définir le format de sortie sur JSON, YAML ou XML pour répondre à différents besoins de traitement des données. L'option --output-query vous permet également de filtrer la sortie et de récupérer des informations spécifiques.
Sécurité renforcée : Pour améliorer la sécurité, ossutil 2,0 vous permet de définir des paramètres sensibles via des variables d'environnement. Cette pratique empêche l'exposition de vos clés dans la ligne de commande et réduit le risque de fuites. De plus, la nouvelle option --dry-run vous permet de vérifier le comportement d'une commande avant son exécution, garantissant ainsi la correction de l'opération.

Configuration rapide avec la commande config

Dans la plupart des cas, utilisez la commande config pour configurer rapidement ossutil. Cette commande génère un fichier de configuration de manière interactive.

Les étapes suivantes utilisent un environnement Linux à titre d'exemple.

Exécutez la commande de configuration.
```
ossutil config
```
Définissez le chemin d'accès du fichier de configuration comme indiqué.
Définissez le chemin d'accès du fichier de configuration selon vos besoins. Par défaut, le fichier de configuration est enregistré sous ~/.ossutilconfig. Appuyez sur Entrée pour accepter la valeur par défaut.
```
Please enter the config file name, the file name can be with a path (default is: /home/user/.ossutilconfig, press enter to use the default path. If you set it to another path, you should specify the path with --config-file option when you use other commands):
```
Définissez la langue de l'outil comme indiqué.

Saisissez CH pour le chinois ou EN pour l'anglais. Par défaut, l'outil utilise la langue de votre système d'exploitation. Ce paramètre prend effet une fois la commande config terminée.

Définissez les paramètres endpoint, AccessKey ID, AccessKey Secret et stsToken comme indiqué. Si vous utilisez un jeton temporaire du Security Token Service (STS) pour accéder à OSS, vous devez configurer le paramètre stsToken. Sinon, laissez-le vide.

Le tableau suivant décrit les paramètres.

Paramètre	Obligatoire	Description
endpoint	Oui	L'endpoint de la région du bucket. Par exemple, pour utiliser l'endpoint public de la région Singapour, définissez la valeur sur `https://oss-ap-southeast-1.aliyuncs.com`. Pour accéder à OSS depuis d'autres services Alibaba Cloud dans la même région, utilisez un endpoint interne. Par exemple, définissez la valeur sur `https://oss-ap-southeast-1-internal.aliyuncs.com`. Pour plus d'informations sur les régions et les endpoints, consultez la section Régions et endpoints. Important En raison d'un changement de politique visant à améliorer la conformité et la sécurité, à partir du 20 mars 2025, les nouveaux utilisateurs d'OSS doivent utiliser un nom de domaine personnalisé (CNAME) pour effectuer des opérations d'API de données sur les buckets OSS situés dans les régions de Chine continentale. Les endpoints publics par défaut sont restreints pour ces opérations. Consultez l'annonce officielle pour obtenir la liste complète des opérations concernées. Si vous accédez à vos données via HTTPS, vous devez associer un certificat SSL valide à votre nom de domaine personnalisé. Cette mesure est obligatoire pour l'accès à la console OSS, car la console impose l'utilisation de HTTPS.
accessKeyID	Oui	La paire de clés AccessKey de votre compte. Pour plus d'informations sur la création d'une paire de clés AccessKey, consultez la section Créer une paire de clés AccessKey. Vous pouvez utiliser un script Resource Orchestration Service (ROS) pour créer rapidement une paire de clés AccessKey pour un utilisateur RAM disposant des autorisations de gestion OSS. Sur la page Create Stack de la console ROS, cochez la case de confirmation sous Security Confirmation, puis cliquez sur Create. Une fois la pile créée, accédez à l'onglet Outputs et copiez la paire de clés AccessKey.
accessKeySecret	Oui
stsToken	Non	Ce paramètre est requis uniquement si vous utilisez un jeton temporaire du STS pour accéder à OSS. Sinon, laissez-le vide. Pour plus d'informations sur la génération d'un stsToken, consultez la section AssumeRole.

Si vous avez spécifié un chemin d'accès personnalisé pour le fichier de configuration à l'étape 2, ajoutez l'option -c pour spécifier le fichier de configuration à chaque exécution de commande.
Par exemple, si le fichier de configuration est enregistré sous /home/config, utilisez le format suivant lors de l'exécution de la commande ls :
```
ossutil -c /home/config ls oss://examplebucket
```

Fichier de configuration

Enregistrez les identifiants et les informations de configuration fréquemment utilisés dans un fichier de configuration par souci de commodité. Le fichier de configuration utilise le format INI et se compose de sections et de paires clé-valeur. Les paramètres de configuration sont enregistrés dans des sections spécifiques. Le tableau suivant décrit les paramètres de configuration courants.

Paramètre	Description	Exemple de code
language	La langue de l'outil ossutil. Valeurs possibles : CH : chinois EN : anglais	`[Credentials] language = CH`
endpoint	L'endpoint de la région où se trouve le bucket.	`[Credentials] endpoint = oss-ap-southeast-1.aliyuncs.com` `[Credentials] endpoint = https://oss-ap-southeast-1.aliyuncs.com`
accessKeyID	La partie de la paire de clés AccessKey qui identifie l'utilisateur pour l'authentification des requêtes.	`[Credentials] accessKeyID = your_accesskey_id`
accessKeySecret	La partie de la paire de clés AccessKey qui signe et authentifie les demandes de commande.	`[Credentials] accessKeySecret = your_accesskey_secret`
stsToken	Le jeton temporaire obtenu auprès du STS pour l'authentification.	`[Credentials] stsToken = your_sts_token`
mode	Le mode d'authentification. Valeurs possibles : AK, StsToken, RamRoleArn et EcsRamRole.	`[Credentials] mode = RamRoleArn`
ramRoleArn	L'Alibaba Cloud Resource Name (ARN) du rôle RAM à assumer lors de l'utilisation du mode d'authentification RamRoleArn.	`[Credentials] ramRoleArn = your_ram_role_arn`
roleSessionName	Le nom de session utilisé en mode RamRoleArn. Si ce paramètre n'est pas défini, une valeur aléatoire est générée.	`[Credentials] roleSessionName = your_ram_role_session_name`
tokenTimeout	La durée d'expiration du jeton temporaire en secondes. Ce paramètre est utilisé en mode RamRoleArn. Valeur par défaut : 3600.	`[Credentials] tokenTimeout = your_token_timeout`
ecsRoleName	Le nom de rôle pour le mode d'authentification EcsRamRole.	`[Credentials] ecsRoleName = your_ecs_role_name`

Pour plus d'informations sur les paramètres de configuration, consultez la section Modifier le fichier de configuration.

Options de ligne de commande

Vous pouvez également spécifier des paramètres à l'aide d'options de ligne de commande, qui ont priorité sur les paramètres du fichier de configuration.

Option	Description	Exemple de code
--loglevel	Le niveau de journalisation. Par défaut, ce paramètre est vide et aucun fichier journal n'est généré. Valeurs possibles : info : affiche les journaux d'informations. debug : affiche des journaux détaillés, y compris les informations sur les requêtes et réponses HTTP.	`ossutil64 commandname options --loglevel debug`
--connect-timeout	Le délai de connexion en secondes. Valeur par défaut : 120.	`ossutil64 commandname options --connect-timeout 60`
--read-timeout	Le délai de lecture en secondes. Valeur par défaut : 1200.	`ossutil64 commandname options --read-timeout 60`
--retry-times	Le nombre de tentatives de nouvelle tentative en cas d'erreur. Valeur par défaut : 10.	`ossutil64 commandname options --retry-times 20`
-e, --endpoint	L'endpoint de la requête.	`ossutil64 commandname options -e oss-ap-southeast-1.aliyuncs.com` `ossutil64 commandname options -e https://oss-ap-southeast-1.aliyuncs.com`
-i, --access-key-id	Les identifiants d'accès utilisés pour accéder à OSS.	`ossutil64 commandname options -i your_access_key_id`
-k, --access-key-secret	Les identifiants d'accès utilisés pour accéder à OSS.	`ossutil64 commandname options -k your_access_key_secret`
-t, --sts-token	Le jeton STS utilisé pour accéder à OSS.	`ossutil64 commandname options -i your_sts_token_accesskey_id -k your_sts_token_accesskey_secret -t your_sts_token`
--mode	Le mode d'authentification. Valeurs possibles : AK, StsToken, RamRoleArn et EcsRamRole. Par défaut, ce paramètre est vide.	L'exemple de code suivant montre comment accéder à OSS en mode AK : `ossutil64 commandname options -i your_accesskey_id -k your_accesskey_secret --mode AK`
--ram-role-arn	L'ARN du rôle RAM à utiliser pour l'authentification.	`ossutil64 commandname options --ram-role-arn your_ram_role_arn`
--role-session-name	Le nom de session à utiliser pour l'authentification.	`ossutil64 commandname options --role-session-name your_ram_session_name`
--token-timeout	La durée de validité du jeton en secondes. Valeur par défaut : 3600.	`ossutil64 commandname options --token-timeout 1800`
--ecs-role-name	Le nom de rôle pour le mode d'authentification EcsRamRole.	`ossutil64 commandname options --ecs-role-name your_ecs_role_name`

Pour plus d'informations sur les options de configuration, consultez la section Options courantes.

Configurer les identifiants d'accès

Vous pouvez configurer les identifiants d'accès de plusieurs manières, par exemple en utilisant un fichier de configuration ou des options de ligne de commande.

Utiliser une paire de clés AccessKey

Cette section utilise un bucket nommé example-bucket dans la région Singapour à titre d'exemple.

Utilisation d'un fichier de configuration

Créez le fichier de configuration suivant et enregistrez-le sous ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
```
Exécutez la commande suivante pour répertorier les objets du bucket :
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
```
Utilisation d'options de ligne de commande

Vous pouvez également transmettre la paire de clés AccessKey directement en tant que paramètres de ligne de commande. L'exemple de code suivant montre comment procéder :
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret ls oss://example-bucket
```
Important
La transmission des identifiants d'accès en tant que paramètres de ligne de commande présente un risque de sécurité, car ils peuvent être enregistrés dans l'historique du shell ou les journaux système. Utilisez cette méthode avec prudence.

Utiliser un jeton temporaire

Cette section utilise un bucket nommé example-bucket dans la région Singapour à titre d'exemple.

Utilisation d'un fichier de configuration

Créez le fichier de configuration suivant et enregistrez-le sous ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
stsToken = yourSecurityToken

Exécutez la commande suivante pour répertorier les objets du bucket :

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

Utilisation d'options de ligne de commande

Vous pouvez également transmettre les identifiants d'accès temporaires en tant que paramètres de ligne de commande. L'exemple de code suivant montre comment procéder :
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret -t yourSecurityToken ls oss://example-bucket
```
Remarque
La transmission des identifiants d'accès en tant que paramètres de ligne de commande présente un risque de sécurité, car ils peuvent être enregistrés dans l'historique du shell ou les journaux système. Utilisez cette méthode avec prudence.

Utiliser un rôle RAM

Cette section utilise un bucket nommé example-bucket dans la région Singapour et un rôle RAM nommé ramRoleArnExample à titre d'exemple.

Utilisation d'un fichier de configuration

Créez le fichier de configuration suivant et enregistrez-le sous ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
ramRoleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example (optional)
tokenTimeout = 1800 (optional)

Exécutez la commande suivante pour répertorier les objets du bucket :

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

Utilisation d'options de ligne de commande

Vous pouvez également transmettre les identifiants d'accès en tant que paramètres de ligne de commande. L'exemple de code suivant montre comment procéder :
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret --mode RamRoleArn --ram-role-arn acs:ram::137918634953****:role/Alice ls oss://example-bucket
```
Remarque
La transmission des identifiants d'accès en tant que paramètres de ligne de commande présente un risque de sécurité, car ils peuvent être enregistrés dans l'historique du shell ou les journaux système. Utilisez cette méthode avec prudence.

Utiliser un rôle RAM d'instance

Sur une instance ECS, vous pouvez utiliser un rôle RAM d'instance pour configurer les identifiants d'accès pour ossutil. Un rôle RAM d'instance vous permet d'associer un rôle à une instance ECS et d'utiliser des identifiants temporaires du STS pour exécuter ossutil au sein de l'instance. Ces identifiants temporaires sont automatiquement générés et renouvelés par le système. Votre application les récupère à partir d'une URL spécifique des métadonnées de l'instance, ce qui élimine la nécessité de gérer des clés à long terme. Cette méthode sécurise votre paire de clés AccessKey et permet un contrôle granulaire des autorisations.

Avant de commencer, créez un rôle RAM d'instance sur l'instance ECS. Pour plus d'informations, consultez la section Créer un rôle RAM d'instance.

Cette section utilise un bucket nommé example-bucket dans la région Singapour et un rôle RAM d'instance nommé EcsRamRoleOss à titre d'exemple.

Utilisation d'un fichier de configuration

Créez le fichier de configuration suivant et enregistrez-le sous ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
mode = EcsRamRole
ecsRoleName = EcsRamRoleOss
```
Exécutez la commande suivante pour répertorier les objets du bucket :
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
```
Utilisation d'options de ligne de commande

Vous pouvez également transmettre la configuration en tant que paramètres de ligne de commande. L'exemple de code suivant montre comment procéder :
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com --mode EcsRamRole --ecs-role-name EcsRamRoleOss ls oss://example-bucket
```

Configurer un endpoint distinct pour un bucket

Lorsque vous utilisez ossutil pour gérer plusieurs buckets dans différentes régions, vous devez configurer un endpoint distinct pour chaque bucket. Vous pouvez procéder de deux manières :

Utilisation d'un fichier de configuration

Dans le fichier de configuration, ajoutez une section [Bucket-Endpoint] pour configurer un endpoint distinct pour chaque bucket spécifié. Le format est le suivant :
```
[Bucket-Endpoint]
bucket1 = endpoint1
bucket2 = endpoint2
...
```
L'exemple suivant montre comment configurer les endpoints pour un bucket dans la région Singapour (example-bucket-sg) et un bucket dans la région Japon (Tokyo) (example-bucket-jp).

Créez le fichier de configuration suivant et enregistrez-le sous ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Endpoint]
example-bucket-sg=oss-ap-southeast-1.aliyuncs.com
example-bucket-jp=oss-ap-northeast-1.aliyuncs.com
```
Exécutez les commandes suivantes pour répertorier les objets des buckets :
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-jp
```
Utilisation d'options de ligne de commande

L'exemple suivant montre comment configurer les endpoints pour un bucket dans la région Singapour (example-bucket-sg) et un bucket dans la région Japon (Tokyo) (example-bucket-jp).

Configurez les informations du compte dans ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
```
Spécifiez l'endpoint à l'aide du paramètre -e.
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig -e oss-ap-northeast-1.aliyuncs.com ls oss://example-bucket-jp
```

Configurer un nom de domaine personnalisé

ossutil vous permet d'accéder aux ressources OSS à l'aide d'un nom de domaine personnalisé. Avant d'utiliser cette fonctionnalité, vous devez mapper le bucket au nom de domaine personnalisé dans le fichier de configuration.

Dans le fichier de configuration, ajoutez une section [Bucket-Cname] pour mapper un bucket à un nom de domaine personnalisé. Le format est le suivant :

[Bucket-Cname]
bucket1 = cname1
bucket2 = cname2
...

L'exemple suivant montre comment accéder à un bucket nommé example-bucket dans la région Singapour à l'aide du nom de domaine personnalisé cname.example-***.com.

Créez le fichier de configuration suivant et enregistrez-le sous ~/.myossutilconfig.

[Credentials]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Cname]
example-bucket=cname.example-***.com

Exécutez la commande suivante pour répertorier les objets du bucket :

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket