Object Storage Service:ossutil 2.0

迅速な統合

ossutil 2.0 のコマンドラインインターフェイスをすぐに使い始めるには、以下の手順を実行してください。

ossutil の設定

設定漏れによる操作失敗を防ぐため、ossutil config コマンドのウィザード機能を使用して、AccessKey ID、AccessKey Secret、およびリージョン ID をすばやく設定してください。詳細設定については、「設定ガイド」を参照し、アクセス認証情報の手動設定について確認してください。

次の例では、設定ウィザードを使用して RAM ユーザーの AccessKey ペアをアクセス認証情報としてすばやく設定する方法を示します。

コマンドの実行

1. バケットを作成します。

   ossutil mb oss://examplebucket

   次の出力は、examplebucket が作成されたことを示しています。

   0.668238(s) 経過

2. ファイルをバケットにアップロードします。

   1. ローカルファイル uploadFile.txt を作成します。

      echo 'Hello, OSS!' > uploadFile.txt

   2. ファイルを examplebucket にアップロードします。

      ossutil cp uploadFile.txt oss://examplebucket

      次の出力は、ファイルが examplebucket にアップロードされたことを示しています。

      成功：合計 1 個のファイル、サイズ 12 B、アップロード完了：(1 個のオブジェクト、12 B)、平均 44 B/s
      
      0.271779(s) 経過

3. ファイルをダウンロードします。

   examplebucket から uploadFile.txt サンプルファイルを localfolder にダウンロードします。

   ossutil cp oss://examplebucket/uploadFile.txt localfolder/

   次の出力は、ファイルが localfolder にダウンロードされたことを示しています。

   成功：合計 1 個のオブジェクト、サイズ 12 B、ダウンロード完了：(1 個のファイル、12 B)、平均 74 B/s
   
   0.162447(s) 経過

4. examplebucket 内のファイルを一覧表示します。

   ossutil ls oss://examplebucket

   次の出力は、examplebucket 内のファイルが一覧表示されたことを示しています。

   最終更新日時                   サイズ(B)  ストレージクラス   ETAG                                  オブジェクト名
   2024-11-26 14:35:29 +0800 CST           12      標準   1103F650EB2C292D179A032D2A97B0F5      oss://examplebucket/uploadFile.txt
   オブジェクト数：1
   
   0.124679(s) 経過

5. examplebucket から uploadFile.txt を削除します。

   ossutil rm oss://examplebucket/uploadFile.txt

   次の出力は、uploadFile.txt が examplebucket から削除されたことを示しています。

   0.295530(s) 経過

6. examplebucket を削除します。

   ossutil rb oss://examplebucket

   次の出力は、examplebucket が削除されたことを示しています。

   0.478659(s) 経過

設定ガイド

ossutil は、設定ファイル、環境変数、およびコマンドラインオプションによる設定をサポートしており、高い柔軟性を提供します。

設定の優先順位

ossutil は、以下の優先順位で設定を読み込みます。

コマンドラインオプション（-i、-k、-e など）> 環境変数（OSS_ACCESS_KEY_ID など）> 設定ファイル（~/.ossutilconfig）

設定ファイル

ossutil は設定ファイルを使用して構成できます。このファイルのデフォルトパスは ~/.ossutilconfig ですが、-c オプションを使用してカスタムパスを指定することもできます。デフォルトの設定ファイルを使用する場合、そのパスを指定する必要はなく、ossutil コマンドを直接実行できます。たとえば：

ossutil ls oss://examplebucket

カスタム設定ファイルパス（例：/path/yourconfig）を使用する場合、-c オプションでパスを指定する必要があります。たとえば：

ossutil -c /path/yourconfig ls oss://examplebucket

[default]
accessKeyID = "your-access-key-id"
accessKeySecret = "your-access-key-secret"

[buckets name]
bucket-name = 
  key=value

[buckets dev-bucket]
bucket-hz-01 = 
  region=cn-hangzhou
bucket-hz-02 = 
  region=cn-hangzhou
  endpoint=test.com
  addressing-style=cname
bucket-bj-01 = 
  region=cn-beijing

環境変数の設定

以下の手順に従って環境変数を設定できます。

設定可能な環境変数は以下のとおりです。

コマンドラインオプションの設定

ossutil は、グローバルコマンドラインオプションを含む複数のコマンドラインオプションを提供します。これらのオプションは最も高い優先順位を持ち、設定ファイルまたは環境変数で設定されたパラメーターを上書きします。

ossutil ls oss://examplebucket -i "your-access-key-id" -k "your-access-key-secret" --region cn-hangzhou

アクセス認証情報の設定

RAM ユーザーの AccessKey ペアの使用

アプリケーションが外部攻撃に対して安全かつ安定した環境で動作し、OSS への長期的なアクセスが必要であり、認証情報を頻繁にローテーションできない場合、Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ペア（AccessKey ID および AccessKey Secret）を使用して認証情報プロバイダーを初期化します。ただし、この方法では AccessKey ペアの手動メンテナンスが必要となり、セキュリティリスクおよびメンテナンスの複雑さが増加します。

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

export OSS_ACCESS_KEY_ID=yourAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourAccessKeySecret
ossutil ls oss://examplebucket

ossutil ls oss://examplebucket -i yourAccessKeyID -k yourAccessKeySecret

STS トークンの使用

アプリケーションが OSS への一時的なアクセスを必要とする場合、Security Token Service (STS) サービスから取得した一時的な認証情報（AccessKey ID、AccessKey Secret、セキュリティトークンなど）を使用して認証情報プロバイダーを初期化できます。この方法では、STS トークンの手動メンテナンスが必要となり、セキュリティリスクおよびメンテナンスの複雑さが増加します。また、OSS に一時的にアクセスするたびに、STS トークンを手動で更新する必要があります。

[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

export OSS_ACCESS_KEY_ID=yourSTSAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourSTSAccessKeySecret
export OSS_SESSION_TOKEN=yourSecurityToken
ossutil ls oss://examplebucket

ossutil ls oss://examplebucket -i yourSTSAccessKeyID -k yourSTSAccessKeySecret -t yourSecurityToken --region cn-hangzhou

RamRoleArn の使用

アプリケーションがクロスアカウントアクセスなどの承認済みの OSS アクセスを必要とする場合、RAMRoleArn を指定することで認証情報プロバイダーを初期化できます。この方法では Security Token Service (STS) トークンを使用します。RAM ロールの Alibaba Cloud Resource Name (ARN) を指定すると、プロバイダーは AssumeRole 操作を呼び出して一時トークンを取得し、セッションの有効期限が切れる前に自動的に更新します。policy パラメーターを設定することで、セッションの権限をさらに制限することもできます。

以下の設定ファイルを作成し、~/.ossutilconfig として保存します。これらの設定は、環境変数またはコマンドラインオプションでは構成できません。

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
roleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example
region=ap-southeast-1

examplebucket のオブジェクトを照会するには、以下のコマンドを実行します。

ossutil ls oss://examplebucket -c ~/.ossutilconfig

EcsRamRole の使用

アプリケーションが ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes のワーカーノード上で実行される場合、EcsRamRole を使用して認証情報プロバイダーを初期化できます。この方法は Security Token Service (STS) トークンに基づいており、EcsRamRole を使用すると、ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes のワーカーノードにロールを関連付けて、インスタンス内で STS トークンを自動的に更新できます。この方法では、AccessKey ペアや STS トークンを提供する必要がないため、手動メンテナンスに起因するリスクが排除されます。EcsRamRole の取得方法については、「CreateRole」をご参照ください。

EcsRamRole モード

[default]
mode = EcsRamRole
# ecsRoleName は省略可能です。設定しない場合、値は自動的に取得されます。
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

ossutil ls oss://examplebucket --mode EcsRamRole

EcsRamRole IMDSv2 パターン

[default]
mode = Ali-EcsRamRole
# ecsRoleName パラメーターは省略可能です。設定しない場合、値は自動的に取得されます。
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

ossutil ls oss://examplebucket --mode Ali-EcsRamRole

OIDCRoleARN の使用

Container Service for Kubernetes (ACK) のワーカーノードに RAM ロールを割り当てると、それらのノード上の Pod で実行されているアプリケーションは、ECS インスタンスにデプロイされたアプリケーションと同様に、メタデータサービス (Metadata Server) から関連付けられたロールの STS トークンを取得できます。ただし、クラスターに信頼できないアプリケーション（ソースコードが公開されていない顧客提出のアプリケーションなど）をデプロイした場合、それらのアプリケーションがワーカーノードのインスタンス RAM ロールの STS トークンをメタデータサービスから取得する可能性があります。クラウドリソースへのセキュリティリスクを防ぎ、信頼できないアプリケーションがアプリケーションレベルの最小権限を適用しながら必要な STS トークンを安全に取得できるようにするには、RAM Roles for Service Accounts (RRSA) 機能を使用します。この方法は内部で STS トークンを使用します。ACK クラスターは、各アプリケーション Pod に対して OpenID Connect (OIDC) トークンファイルを作成してマウントし、関連する設定情報を環境変数に注入します。認証情報ツールは、この設定を環境変数から取得し、STS の AssumeRoleWithOIDC 操作を呼び出して、アタッチされたロールの STS トークンを取得します。この方法では AccessKey ペアや既存の STS トークンが不要なため、手動メンテナンスに伴うリスクが排除されます。詳細については、「RRSA に基づく Pod の権限分離」をご参照ください。

以下の設定ファイルを作成し、~/.ossutilconfig として保存します。この設定は、環境変数やコマンドラインオプションでは構成できません。

[default]
mode = oidcRoleArn
# OIDC プロバイダーの Alibaba Cloud Resource Name (ARN) を指定します。形式は acs:ram::account-id:oidc-provider/provider-name です。
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# OIDC トークンのファイルパスを指定します。
OIDCTokenFilePath=OIDCTokenFilePath
# 引き受けるロールの ARN を入力します。形式は acs:ram::113511544585****:oidc-provider/TestOidcProvider です。
roleArn=acs:ram::113511544585****:role/testoidc
# 異なるトークンを区別するためのカスタムロールセッション名です。
roleSessionName= TestOidcAssumedRoleSession
region=ap-southeast-1

examplebucket のオブジェクトを照会するには、以下のコマンドを実行します。

ossutil ls oss://examplebucket -c ~/.ossutilconfig

外部プロセスからの認証情報の取得

ossutil は、外部コマンドを実行することで独立した外部プロセスを起動できます。このプロセスは実行され、その結果を標準出力を介して ossutil に返します。このような外部プロセスを使用して認証情報を取得できます。

外部コマンドを使用して、以下の形式で長期または一時的な認証情報を取得できます。

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk"
}

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
  "Expiration" : "2023-12-29T07:45:02Z",
  "SecurityToken" : "token"
}

以下の設定ファイルを作成し、~/.ossutilconfig に保存します。これらの設定は、環境変数またはコマンドラインオプションでは構成できません。

[default]
mode = Process
credentialProcess = user-cmd
region=ap-southeast-1

examplebucket のオブジェクトを照会するには、以下のコマンドを実行します。

ossutil ls oss://examplebucket -c ~/.ossutilconfig

匿名アクセス

公開読み取り権限を持つ OSS リソースにのみアクセスする必要がある場合は、認証情報を提供せずに匿名アクセスを使用できます。

ossutil cat oss://bucket/public-object --mode Anonymous

コマンドリファレンス

ossutil を使用して、高レベルコマンド、API レベルのコマンド、ヘルパーコマンドの 3 種類のコマンドを実行できます。

ossutil command [argument] [flags]  

ossutil command subcommond [argument] [flags]  

ossutil topic

{
  "CORSRule": {
    "AllowedOrigin": ["www.aliyun.com"],
    "AllowedMethod": ["PUT","GET"],
    "MaxAgeSeconds": 10000
  }
}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration file://cors-configuration.json

{"CORSRule":{"AllowedOrigin":["www.aliyun.com"],"AllowedMethod":["PUT","GET"],"MaxAgeSeconds":10000}}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration  "{\"CORSRule\":{\"AllowedOrigin\":[\"www.aliyun.com\"],\"AllowedMethod\":[\"PUT\",\"GET\"],\"MaxAgeSeconds\":10000}}"

cat cors-configuration.json | ossutil api put-bucket-cors --bucket examplebucket --cors-configuration -

ossutil api get-bucket-cors --bucket bucketexample
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>www.aliyun.com</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <MaxAgeSeconds>10000</MaxAgeSeconds>
  </CORSRule>
  <ResponseVary>false</ResponseVary>
</CORSConfiguration>

ossutil api get-bucket-cors --bucket bucketexample --output-format json
{
  "CORSRule": {
    "AllowedMethod": [
      "PUT",
      "GET"
    ],
    "AllowedOrigin": "www.aliyun.com",
    "MaxAgeSeconds": "10000"
  },
  "ResponseVary": "false"
}

ossutil api get-bucket-cors --bucket bucketexample --output-query CORSRule.AllowedMethod --output-format json
[
  "PUT",
  "GET"
]

ossutil stat oss://bucketexample
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131072
...
StandardObjectCount         : 119212
StandardStorage             : 66756852803
Storage                     : 66756852813
StorageClass                : Standard
TransferAcceleration        : Disabled

ossutil stat oss://bucketexample --human-readable
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131.072k
...
StandardObjectCount         : 119.212k
StandardStorage             : 66.757G
Storage                     : 66.757G
StorageClass                : Standard
TransferAcceleration        : Disabled

コマンドラインオプション

一部のコマンドライン操作では、ターゲットを指定したりオプションを設定したりするために追加のパラメーターが必要ですが、そうでないものもあります。パラメーターを取るコマンドの場合、目的の機能を実現するために適切なパラメーター値を指定します。たとえば：

ossutil ls --profile dev

コマンド ossutil ls --profile dev では、パラメーター値 dev を使用して特定の設定ファイルを指定できます。パラメーターを取るオプションは通常、オプション名とパラメーター値を区切るためにスペースまたは等号（=）を必要とします（例：--profile dev または --profile=dev）。パラメーター値にスペースが含まれる場合は、コマンドが正しく解析されるように、値全体を二重引用符で囲む必要があります（例：--description "OSS bucket list"）。

よくある質問

ossutil コマンドを実行すると、「region must be set in sign version 4」というエラーが報告される

原因：ossutil 2.0 の設定時にリージョン ID が構成されていませんでした。

解決策：ossutil を使用する際に設定項目が欠落していることによる操作の失敗を防ぐため、必要な基本項目（AccessKey ID、AccessKey Secret、リージョン ID）を必ず構成してください。署名が V4 にアップグレードされたため、リージョン ID は特に重要であり、必須項目となっています。リージョン ID の取得方法については、「リージョンとエンドポイント」をご参照ください。