[Azure] Linux版 AzCopyの使い方(V7とV10比較)

AzCopyは、ストレージアカウント間のデータコピーに利用できるコマンドライン ユーティリティです。現在(2020/05/21 時点)の最新バージョンは"V10"ですが、使い方を検索すると「以前のバージョン」(Linux版は"V7")の情報もたくさん出てきます。

V7とV10は認証方法・パラメタなどが違い、ほぼ別物となっているため、この記事では両者の使い方の違いをまとめました。

V10は色々機能が追加されS3とのコピーなどもできるようになっていますが、この記事では比較の観点から以下の利用方法のみ記載しています。

- Blobをローカルにコピー、あるいはBlob間コピー
- プロキシ経由での使用

# 準備作業

まずはコピーに必要なAzureの権限、Blob設定についてです。

コピー元、コピー先によってはこの全てを設定する必要はありません。[V7の使い方](https://qiita.com/VA_nakatsu/private/84e45e4566b11134f53c#v7%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) 、[V10の使い方](https://qiita.com/VA_nakatsu/private/84e45e4566b11134f53c#v10%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) の使い方を先に確認し、必要に応じて設定して下さい。

## Shared Access Signature(SAS)

Azure Portalで ストレージアカウント -> Shared Access Signature から発行できます。

|![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/172826/b997e32e-5d7d-a56b-a4a5-64e42ab53e72.png)|
|:-:|

Blobの場合は「コンテナー」と「オブジェクト」のチェックを忘れないようにして下さい。「SASと接続文字列を生成する」ボタンを押すと下にSASが表示されます。

|![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/172826/6b9505ff-d933-3ee9-6fba-2639d3f7f972.png)|
|:-:|

SASトークン（`?sv=`から始まる文字列）をコピーしておきます。

## アクセスキー

Azure Portalで ストレージアカウント -> アクセスキー で確認できます。

|![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/172826/b2363bae-bc9e-9777-2935-fc6610842970.png)|
|:-:|

キーが2つ（上記スクリーンショットは1の部分のみです）表示されているのでどちらかコピーしておきます。

## サービスプリンシパル

サービスプリンシパルはV10のみ対応しています。まず Azureポータル -> Azure Active Directory からアプリを新規登録します。

|![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/172826/732b8382-49ba-f232-1d02-0ea28c107708.png)|
|:-:|

作成後、アプリケーションのメニュー「証明書とシークレット」からクライアントシークレットを発行します。

|![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/172826/15157cf8-8c64-0710-1622-5c3ece41eeb0.png)|
|:-:|

シークレットの他、概要で表示されている アプリケーション(クライアント)ID と ディレクトリ(テナント)ID が認証に必要なためコピーしておきます。

|![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/172826/b8b67550-513b-baf7-5779-ee53d708750c.png)|
|:-:|

最後に、サブスクリプションの「アクセス制御(IAM)」メニューからアプリケーションに"ストレージBLOBデータ共同作成者"権限を付与します。

|![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/172826/a3c4e4bc-052b-8355-ac27-28df7cbd58c9.png)|
|:-:|

# V7の使い方

まずは根強い人気の(?) V7の利用手順です。

## インストール(V7)

[以前のバージョンのAZcopyの使用(英語)](https://docs.microsoft.com/ja-jp/previous-versions/azure/storage/storage-use-azcopy-linux) に記載があります。 install.shの実行、あるいはapt-get install azcopyで/usr/bin/azcopyにインストールされます。

引数無しで実行するとバージョンとヘルプが表示されます。

```
$ /usr/bin/azcopy
------------------------------------------------------------------------------
azcopy 7.3.0-netcore Copyright (c) 2018 Microsoft Corp. All Rights Reserved.
------------------------------------------------------------------------------
# azcopy is designed for high-performance uploading, downloading, and copying
data to and from Microsoft Azure Blob, and File storage.

# Command Line Usage:
    azcopy --source <source> --destination <destination> [options]

# Options:
    [--source-key] [--dest-key] [--source-sas] [--dest-sas] [--verbose] [--resume]
    [--config-file] [--quiet] [--parallel-level] [--source-type] [--dest-type]
    [--recursive] [--include] [--check-md5] [--dry-run] [--preserve-last-modified-time]
    [--exclude-newer] [--exclude-older] [--sync-copy] [--set-content-type] [--blob-type]
    [--delimiter] [--include-snapshot] [--block-size-in-mb]

------------------------------------------------------------------------------
For azcopy command-line help, type one of the following commands:
# Detailed command-line help for azcopy      ---   azcopy --help
# Detailed help for any azcopy option        ---   azcopy --help source-key
# Command line samples                       ---   azcopy --help sample
You can learn more about azcopy at http://aka.ms/azcopy.
------------------------------------------------------------------------------
```

## 実行手順(V7)

コピー元、コピー先を以下のようにオプションで指定します。

```
azcopy --source <コピー元のパス> \
       --source-key <コピー元のアクセスキー(コピー元がBlobの場合に、--source-sasとどちらかを指定)> \
       --source-sas <コピー元のSAS(コピー元がBlobの場合に、--source-keyとどちらかを指定)> \
       --destination <コピー先のパス> \
       --dest-key <コピー先のアクセスキー(コピー元がBlobの場合に、--dest-sasとどちらかを指定)> \
       --dest-sas <コピー先のSAS(コピー元がBlobの場合に、--dest-keyとどちらかを指定)>
```

- パスの記法について、Blobの場合は `https://<ストレージアカウント名>.blob.core.windows.net/<コンテナ名>/<オブジェクト名(ファイル名)>` という形式で指定します。事前準備で発行したSASトークンかアクセスキーのどちらかをオプションとして追加する必要があります。
　　・SASを使用する場合は、--source-sas あるいは --dest-sas オプションでSASを指定します。ちょっと違和感がありますが、`?sv=`で始まるSASトークンを値として指定します。
　　・アクセスキーを使用する場合は、--source-key あるいは --dest-key オプションでアクセスキーを指定します。

- コピー元、コピー先がローカルファイルの場合は(当然ですが) sas, key のどちらも指定不要です。

- プロキシ経由でBlobに接続する場合は、環境変数 `HTTPS_PROXY` でプロキシを設定します。

## 実行例(V7)

```shell-session
＃ プロキシ設定
$ export HTTPS_PROXY=http://proxyserver.yoursserver.com:8080
$ export | grep PROXY
declare -x HTTPS_PROXY="http://proxyserver.yoursserver.com:8080"

＃ SASを使ったコピーの例
$ azcopy --source ./azcopy.tar \
> --destination 'https://storageaccountname.blob.core.windows.net/azcopytest/azcopy.tar' \
> --dest-sas '?sv=2019-10-10&ss=b&srt=co&sp=rwlacx&se=2020-05-19T09:58:42Z&st=2020-05-19T01:58:42Z&spr=https&sig=vqZxxxxxxxxxxxxxxxxxxxxxxxxxxx%3D'
Finished 1 of total 1 file(s).
[2020/05/19 11:34:46] Transfer summary:
-----------------
Total files transferred: 1
Transfer successfully:   1
Transfer skipped:        0
Transfer failed:         0
Elapsed time:            00.00:00:05

＃ アクセスキーを使ったコピーの例
$ azcopy --source 'https://storageaccountname.blob.core.windows.net/azcopytest/azcopy.tar' \
> --source-key 'UAQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8A==' \
> --destination ./azcopy.tar
Finished 1 of total 1 file(s).
[2020/05/19 10:58:06] Transfer summary:
-----------------
Total files transferred: 1
Transfer successfully:   1
Transfer skipped:        0
Transfer failed:         0
Elapsed time:            00.00:00:11
```

# V10の使い方

続いてV10の利用手順です。

## インストール(V10)

[AzCopy を使ってみる](https://docs.microsoft.com/ja-jp/azure/storage/common/storage-use-azcopy-v10?toc=/azure/storage/blobs/toc.json) に記載があります。V10はインストール形式ではなく、tarをダウンロードして解凍し、できたazcopyバイナリを任意の場所に置いて実行します（パスを通して下さい）。

V7と同じく引数無しで実行するとバージョンとヘルプが表示されます。

```
$ azcopy
AzCopy 10.4.3
Project URL: github.com/Azure/azure-storage-azcopy

AzCopy is a command line tool that moves data into and out of Azure Storage.
To report issues or to learn more about the tool, go to github.com/Azure/azure-storage-azcopy

The general format of the commands is: 'azcopy [command] [arguments] --[flag-name]=[flag-value]'.

Usage:
  azcopy [command]

Available Commands:
  bench       Performs a performance benchmark
  copy        Copies source data to a destination location
  doc         Generates documentation for the tool in Markdown format
  env         Shows the environment variables that you can use to configure the behavior of AzCopy.
  help        Help about any command
  jobs        Sub-commands related to managing jobs
  list        List the entities in a given resource
  login       Log in to Azure Active Directory (AD) to access Azure Storage resources.
  logout      Log out to terminate access to Azure Storage resources.
  make        Create a container or file share.
  remove      Delete blobs or files from an Azure storage account
  sync        Replicate source to the destination location

Flags:
      --cap-mbps float                      Caps the transfer rate, in megabits per second. Moment-by-moment throughput might vary slightly from the cap. If this option is set to zero, or it is omitted, the throughput isn't capped.
  -h, --help                                help for azcopy
      --output-type string                  Format of the command's output. The choices include: text, json. The default value is 'text'. (default "text")
      --trusted-microsoft-suffixes string   Specifies additional domain suffixes where Azure Active Directory login tokens may be sent.  The default is '*.core.windows.net;*.core.chinacloudapi.cn;*.core.cloudapi.de;*.core.usgovcloudapi.net'. Any listed here are added to the default. For security, you should only put Microsoft Azure domains here. Separate multiple entries with semi-colons.
      --version                             version for azcopy

Use "azcopy [command] --help" for more information about a command.
```

## 実行手順(V10)

V10では、サブコマンドが追加されました。最初にログインコマンド(azcopy login)でログインし、コピーコマンド(azcopy copy)でコピーするようになります。コピー元とコピー先はLinuxのcpコマンド同様の指定になりました。

クライアントシークレット、アプリケーションID、テナントIDは事前準備のサービスプリンシパル作成で確認したものを使用して下さい。

```
$ export AZCOPY_SPA_CLIENT_SECRET=<クライアントシークレット>

$ azcopy login --service-principal -application-id <アプリケーションID> --tenant-id <テナントID>

$ azcopy copy <コピー元のパス>  <コピー先のパス>
```

- ただし現状(2020-05-21 現在)、loginで取得したサービスプリンシパルの権限は<font color="red">コピー先のパスに対してのみ有効</font>となります。<font color="blue">コピー元にはSASトークンを付加する必要</font>があります。

> 現在のリリースでは、このシナリオに以下の制限があります。
> 各ソース URL の末尾に SAS トークンを追加する必要があります。 Azure Active Directory (AD) を使用して認証資格情報を提供する場合、SAS トークンを省略できるのは宛先 URL だけです。

　SASトークンはBlobのURL末尾に付加し、その場合はパスが
　`https://<ストレージアカウント名>.blob.core.windows.net/<コンテナ名>/<オブジェクト名(ファイル名)><SASトークン>`
　という形式になります。V7のように別パラメタとしての指定ではありません。

- プロキシ経由でBlobに接続する場合は、V7と同じ環境変数 `HTTPS_PROXY` でプロキシを設定します。

## 実行例(V10)

```shell-session
＃ プロキシ設定
$ export HTTPS_PROXY=http://proxyserver.yoursserver.com:8080
$ export | grep PROXY
declare -x HTTPS_PROXY="http://proxyserver.yoursserver.com:8080"

＃ クライアントシークレット設定
$ export AZCOPY_SPA_CLIENT_SECRET=8lz_xxxxxxxxxxxz_xxxxxxxx-xxxx2N
$ export | grep AZCOPY
declare -x AZCOPY_SPA_CLIENT_SECRET="8lz_xxxxxxxxxxxz_xxxxxxxx-xxxx2N"

＃ ログイン
$ azcopy login --service-principal \
> --application-id 2c0xxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxf57 \
> --tenant-id 53cxxxxx-xxxx-xxxx-xxxxx-xxxxxxxxx444
INFO: If you set an environment variable by using the command line, that variable will be readable in your command line history. Consider clearing variables that contain credentials from your command line history.  To keep variables from appearing in your history, you can use a script to prompt the user for their credentials, and to set the environment variable.
INFO: SPN Auth via secret succeeded.

＃ Blobにコピーする
$ azcopy copy './azcopy10.4.3.tar' 'https://storageaccountname.blob.core.windows.net/test/azcopy10.4.3.tar'
INFO: Scanning...
INFO: Any empty folders will not be processed, because source and/or destination doesn't have full folder support
Job c02bxxxx-xxxx-xxxx-xxxx-xxxxxxxx39d5 has started
Log file is located at: /home/azureuser/.azcopy/c02bxxxx-xxxx-xxxx-xxxx-xxxxxxxx39d5.log
57.1 %, 0 Done, 0 Failed, 1 Pending, 0 Skipped, 1 Total, 2-sec Throughput (Mb/s): 78.1865
Job c02bxxxx-xxxx-xxxx-xxxx-xxxxxxxx39d5 summary
Elapsed Time (Minutes): 0.0667
Number of File Transfers: 1
Number of Folder Property Transfers: 0
Total Number of Transfers: 1
Number of Transfers Completed: 1
Number of Transfers Failed: 0
Number of Transfers Skipped: 0
TotalBytesTransferred: 19558400
Final Job Status: Completed

＃ Blob間コピーの例、コピー元は同じコンテナであってもSASトークンを付ける必要がある
$ azcopy copy 'https://storageaccountname.blob.core.windows.net/test/azcopy10.4.3.tar?sv=2019-10-10&ss=b&srt=co&sp=rwdlacx&se=2020-05-18T19:00:34Z&st=2020-0518T11:00:34Z&spr=https&sig=r%2Byxxxxxxxxxxxxxxxxxxxxxxxxxxxxx%3D' \
> 'https://storageaccountname.blob.core.windows.net/test/azcopy10.4.3_copy.tar'
INFO: Scanning...
INFO: Any empty folders will not be processed, because source and/or destination doesn't have full folder support
Job c02xxxxx-xxxx-xxxx-xxxx-xxxxxxxx9d5 has started
Log file is located at: /home/azureuser/.azcopy/c02xxxxx-xxxx-xxxx-xxxx-xxxxxxxx9d5.log
57.1 %, 0 Done, 0 Failed, 1 Pending, 0 Skipped, 1 Total, 2-sec Throughput (Mb/s): 78.1865
Job c02xxxxx-xxxx-xxxx-xxxx-xxxxxxxx9d5 summary
Elapsed Time (Minutes): 0.0667
Number of File Transfers: 1
Number of Folder Property Transfers: 0
Total Number of Transfers: 1
Number of Transfers Completed: 1
Number of Transfers Failed: 0
Number of Transfers Skipped: 0
TotalBytesTransferred: 19558400
Final Job Status: Completed
```

使い方は以上です。

V10で追加された機能については、[コマンドリファレンス](https://docs.microsoft.com/ja-jp/azure/storage/common/storage-ref-azcopy) が公開されているので参照して下さい。

# 参考資料

- [【V10】azcopy - Microsoft Docs](https://docs.microsoft.com/ja-jp/azure/storage/common/storage-ref-azcopy)
- [【V10】AzCopy を使ってみる](https://docs.microsoft.com/ja-jp/azure/storage/common/storage-use-azcopy-v10?toc=/azure/storage/blobs/toc.json)
- [【V10】AzCopy と Blob Storage でデータを転送する](https://docs.microsoft.com/ja-jp/azure/storage/common/storage-use-azcopy-blobs)
- [【V10】AzCopy を使用して Amazon S3 から Azure Storage にデータをコピーする](https://docs.microsoft.com/ja-jp/azure/storage/common/storage-use-azcopy-s3?toc=/azure/storage/blobs/toc.json)
- [【V7】以前のバージョンのAZcopyの使用(英語)](https://docs.microsoft.com/ja-jp/previous-versions/azure/storage/storage-use-azcopy-linux)