グローバル コマンドライン オプション
説明
gsutil は、gsutil のトップレベル コマンドや個々のサブコマンド(cp、rm など)のオプションをサポートしています。トップレベルのオプションを使用すると、コマンドに対する gsutil の動作を制御できます。たとえば、次のコマンドで説明しましょう。
gsutil -m cp -p file gs://bucket/obj
-m オプションは gsutil に適用されますが、-p オプションは cp サブコマンドに適用されます。
オプション
- -D
HTTP リクエスト / ヘッダー、サポート リクエストの送信で必要になる追加のデバッグ情報(例外のスタック トレースなど)を表示します。
- -DD
-D と同様、HTTP アップストリーム ペイロード。
- -h
特定の HTTP ヘッダーを指定できます。例:
gsutil -h "Cache-Control:public,max-age=3600" \ -h "Content-Type:text/html" cp ...
スペースを含むヘッダー / 値は引用符で囲む必要があります(例: "Content-Disposition: attachment; filename=filename.ext")。引用符で囲まないと、シェルがこの値を複数の引数に分割します。
次のヘッダーはオブジェクト メタデータとして保存され、オブジェクトに対する今後のリクエストで使用されます。
Cache-Control Content-Disposition Content-Encoding Content-Language Content-Type
次のヘッダーは、データの整合性を確認するために使用されます。
Content-MD5
gsutil では、次のように、一致する Cloud Storage Provider の接頭辞を含むカスタム メタデータ ヘッダーもサポートされます。
x-goog-meta-
gs:// URL の場合、キャッシュ制御ヘッダーは API 固有になります。XML API は、キャッシュ制御ヘッダーを受け入れ、オブジェクトのダウンロードでヘッダーを返します。JSON API は、public、private、no-cache、max-age、no-transform のキャッシュ制御ヘッダーのみを受け入れます。
アップロード後にオブジェクトのメタデータ フィールドを設定する方法については、gsutil help setmeta をご覧ください。
- -i
構成された認証情報を使用して、サービス アカウントになり代わることが可能です。次に例を示します。
gsutil -i "service-account@google.com" ls gs://pub
この設定は XML API と S3 では無視されます。サービス アカウントになりすます方法について詳しくは、gsutil help creds をご覧ください。
- -m
サポートされている操作(acl ch、acl set、cp、mv、rm、rsync、setmeta)を並行して実行できます。比較的高速なネットワーク接続で大量のファイルに操作を実行する場合、このオプションを使用すると、パフォーマンスが大幅に向上します。
gsutil は、マルチスレッドとマルチ処理を組み合わせて指定された操作を実行します。スレッドとプロセッサの数は、それぞれ
parallel_thread_count
とparallel_process_count
によって決まります。これらの値は .boto 構成ファイルで設定するか、-o
トップレベル フラグを使用して個々のリクエストで指定します。gsutil にはリクエストをスロットルする機能がないため、これらの値でテストする必要があります。最適な値は、ネットワーク速度、CPU の数、使用可能なメモリなど、さまざまな要因によって変わります。-m オプションを使用すると、ネットワーク帯域幅を大量に消費する可能性があります。低速なネットワークでは問題やパフォーマンスの低下が起きる可能性があります。たとえば、他の多くの重要なジョブでも使用されているネットワーク リンクで大規模な rsync オペレーションを開始すると、それらのジョブでパフォーマンスが低下することがあります。同様に、-m オプションを使用すると、ローカル ディスクを「スラッッシュ」し、パフォーマンスが低下する可能性があります(この問題は特にローカルですべての処理を実行している場合に発生します)。
このような問題を回避するには、
parallel_thread_count
とparallel_process_count
の値を小さくするか、-m オプションの使用を中止してください。gsutil が使用する I/O 容量を制限し、ローカル ディスクの占有を回避するために使用できるツールの 1 つが ionice です。このツールは多くの Linux システムに組み込まれています。たとえば、次のコマンドは gsutil の I/O 優先度を下げます。これにより、ローカル ディスクが占有されなくなります。ionice -c 2 -n 7 gsutil -m rsync -r ./dir gs://some bucket
転送全体が完了する前に(たとえば、1,000 個のファイルのうち 300 個が転送された後で)並列転送のダウンロードやアップロードが失敗した場合、転送を最初からやり直す必要があります。
また、-m フラグを無効にすると、ほとんどのコマンドでエラーが発生しますが、-m が複数のスレッドまたはプロセスで有効になっている場合、コマンドはオペレーションを続行します。失敗したオペレーションはコマンドの終了時に例外として報告されます。
- -o
現在のコマンドの boto 構成ファイルの値を
<section>:<name>=<value>
の形式でオーバーライドします。たとえば、gsutil -o "GSUtil:parallel_thread_count=4" ...
のように指定します。これによって、gsutil インテグレーション テストにオプションが渡されることはありません。また、boto 構成ファイル内に保存されている値が変更されることもありません。- -q
gsutil がサイレント モードで操作を実行します。エラーは報告されますが、ファイルのコピーや削除の進捗状況は表示されません。このオプションは、cron ジョブから gsutil を実行してログをファイルに出力する場合や、ログにエラーだけを記録する場合に便利です。
- -u
リクエストに対して課金されるユーザー プロジェクトの ID または番号を指定できます。例:
gsutil -u "bill-this-project" cp ...