Java 用 Azure ファイル共有クライアントライブラリ

[アーティクル]
10/25/2023

サーバーメッセージブロック (SMB) プロトコルは、現在オンプレミスで使用される推奨されるファイル共有プロトコルです。 Microsoft Azure File Share サービスを使用すると、SMB クライアントアプリケーションを書き換えることなく、Azure のサービスとしてのクラウドインフラストラクチャ (IaaS) SMB の可用性とスケーラビリティを活用できます。

Azure File Share サービス共有に格納されているファイルには、SMB プロトコルと REST API を介してアクセスできます。ファイル共有サービスには、ストレージアカウント、共有、ディレクトリ、ファイルの 4 つのリソースが用意されています。共有によって複数のファイルを整理することができます。また、クラウドでホストされる SMB ファイル共有としてマウントすることもできます。

ソースコード | API リファレンスドキュメント | REST API のドキュメント | 製品ドキュメント | サンプル

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

GA バージョンのライブラリに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

次に、バージョンタグのない依存関係セクションに直接依存関係を含めます。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-share</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-file-share</artifactId>
  <version>12.20.1</version>
</dependency>

ストレージアカウントを作成する

ストレージアカウントを作成するには、Azure Portal または Azure CLI を使用できます。

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

クライアントを認証する

ストレージサービス (ファイル共有サービス、共有、ディレクトリ、MessageId、ファイル) と対話するには、Service Client クラスのインスタンスを作成する必要があります。これを可能にするには、ストレージアカウントのアカウント SAS (共有アクセス署名) 文字列が必要です。詳細については、SAS トークンに関するページを参照してください

資格情報の取得

SAS トークン
- 次の Azure CLI スニペットを使用して、ストレージアカウントから SAS トークンを取得します。
```
az storage file generate-sas
    --name {account name}
    --expiry {date/time to expire SAS token}
    --permission {permission to grant}
    --connection-string {connection string of the storage account}
```
```
CONNECTION_STRING=<connection-string>

az storage file generate-sas
    --name javasdksas
    --expiry 2019-06-05
    --permission rpau
    --connection-string $CONNECTION_STRING
```
- または、Azure Portal からアカウント SAS トークンを取得します。
  1. ストレージアカウントに移動します。
  2. [Shared Access Signature]$共有アクセス署名$ をクリックします。
  3. [SAS と接続文字列の生成] をクリックします。
共有キーの資格情報
- 共有キー資格情報を作成するには 2 つの方法があります。1 つ目は、ストレージアカウント名とアカウントキーを使用することです。 2 つ目は、ストレージ接続文字列を使用することです。
  1. アカウント名とアカウントキーを使用します。
    1. アカウント名はストレージアカウント名です。
    2. ストレージアカウントに移動します。
    3. [アクセスキー] タブを選択します。
    4. キー 1 またはキー 2 の "Key" 値をコピーします。
  2. 接続文字列を使用する
    1. ストレージアカウントに移動します。
    2. [アクセスキー] タブを選択します。
    3. キー 1 またはキー 2 の "接続文字列" の値をコピーします。

主要な概念

URL 形式

ファイル共有は、次の URL 形式を使用してアドレス指定できます。

https://<storage account>.file.core.windows.net/<share>

次の URL を使用すると、図のいずれかのキューをアドレス指定できます。

https://myaccount.file.core.windows.net/images-to-download

リソースの URI の構文

ストレージアカウントの場合、キュー操作のベース URI にはアカウントの名前だけが含まれます。

https://myaccount.file.core.windows.net

file の場合、ベース URI にはアカウントの名前とディレクトリ/ファイルの名前が含まれます。

https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile

例外処理

以下の shareServiceClientshareServiceClient セクションから生成されたを使用します。

try {
    shareServiceClient.createShare("myShare");
} catch (ShareStorageException e) {
    logger.error("Failed to create a share with error code: " + e.getErrorCode());
}

リソース名

共有、ディレクトリ、またはファイルを参照する URI は一意であることが必要です。ストレージアカウント内では、すべての共有名は一意である必要があります。共有またはディレクトリ内のすべてのファイルの名前もその共有またはディレクトリ内で一意である必要があります。

共有、ディレクトリ、またはファイルを名前付け規則に違反する名前で作成しようとすると、要求はステータスコード 400 (Bad Request) で失敗します。

ファイル共有サービス名の規則は、SMB 共有名の SMB プロトコルで規定されている規則よりも制限が厳しく、BLOB サービスとファイルサービスがコンテナーと共有に対して同様の名前付け規則を共有できるようにします。共有の名前付けの制約は、次のとおりです。

共有名は有効な DNS 名にする必要があります。
共有名は、文字または数字で始まり、文字、数字、またはダッシュ (-) 文字だけを使用できます。
すべてのダッシュ文字は、その直前および直後に文字または数字が使用されている必要があります。連続するダッシュ文字は、共有名では使用できません。
共有名のすべての文字は、小文字にする必要があります。
共有名の長さは 3 ～ 63 文字にする必要があります。

ディレクトリ名とファイル名

ディレクトリ名とファイル名の Azure File Share サービスの名前付け規則は次のとおりです。

共有ディレクトリ名とファイル名では、大文字と小文字が区別されず、大文字と小文字が区別されません。
共有ディレクトリとファイルコンポーネントの名前の長さは 255 文字以下にする必要があります。
共有ディレクトリ名をスラッシュ文字 (/) で終えることはできません。使用した場合、自動的に削除されます。
共有ファイル名の末尾をスラッシュ文字 (/) にすることはできません。
URL の予約文字は適切にエスケープしてください。
次の文字は使用できません。 " \ / : | < > * ?
無効な URL パス文字は使用できません。 NTFS ファイル名で有効な \uE000 などのコードポイントは、有効な Unicode 文字ではありません。また、制御文字 (0x00 ～ 0x1F、\u0081 など) など、一部の ASCII 文字または Unicode 文字も使用できません。 HTTP/1.1 の Unicode 文字列を管理する規則については、 RFC 2616、セクション 2.2: 基本規則および RFC 3987 を参照してください。
次のファイル名は使用できません:LPT1、LPT2、LPT3、LPT4、LPT5、LPT6、LPT7、LPT8、LPT9、COM1、COM2、COM4、COM5、COM6、COM7、COM8、COM9、PRN、AUX、NUL、CON、CLOCK$、ドット文字 (.)、および 2 つのドット文字 (..)。

メタデータ名

共有リソースまたはファイルリソースのメタデータは、リソースに関連付けられた名前と値のペアとして保存されます。ディレクトリには、メタデータはありません。メタデータ名は、C# 識別子の名前付け規則に従う必要があります。

メタデータ名の作成時に指定された大文字と小文字の違いは維持されますが、設定時または読み取り時には大文字と小文字は区別されません。リソースに対して同じ名前の複数のメタデータヘッダーが送信された場合、Azure File サービスはステータスコード 400 (Bad Request) を返します。

ファイル共有サービス REST API は、アカウントに対する操作を提供し、ファイルサービスのプロパティを管理します。これにより、共有の一覧表示と削除、ファイルサービスプロパティの取得と設定を行うことができます。 SASToken を作成したら、を使用して ${accountName}をshareServiceClient構築できます。${sasToken}

String shareServiceURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareServiceClient shareServiceClient = new ShareServiceClientBuilder().endpoint(shareServiceURL)
    .sasToken(SAS_TOKEN).buildClient();

共有リソースには、その共有のメタデータとプロパティが含まれます。これにより、作成、スナップショットの作成、共有の削除、共有プロパティの取得、メタデータの設定、ACL の取得と設定 (アクセスポリシー) の操作が可能になります。 ACL (アクセスポリシー) の取得と設定は、ShareClient と ConnectionString でのみ使用できます。

SASToken を取得したら、を使用して共有クライアントを${accountName}${shareName}構築できます。${sasToken}

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareClient shareClient = new ShareClientBuilder().endpoint(shareURL)
    .sasToken(SAS_TOKEN).shareName(shareName).buildClient();

ConnectionString を取得したら、を使用して共有クライアントを${accountName}${shareName}構築できます。${connectionString}

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareClient shareClient = new ShareClientBuilder().endpoint(shareURL)
    .connectionString(CONNECTION_STRING).shareName(shareName).buildClient();

共有する `TokenCredential`

TokenCredential を取得したら、、、 ShareTokenIntentを使用して共有クライアントを${accountName}${shareName}構築できます。 ShareTokenIntent.BACKUP は、バックアップ/管理者の種類の操作を目的とした要求を指定します。つまり、すべてのファイル/ディレクトリ ACL がバイパスされ、完全なアクセス許可が付与されます。を使用 ShareTokenIntent.BACKUPするには、ユーザーに必要な RBAC アクセス許可が必要です。

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);

ShareClient serviceClient = new ShareClientBuilder()
    .endpoint(shareURL)
    .credential(tokenCredential)
    .shareTokenIntent(ShareTokenIntent.BACKUP)
    .shareName(shareName)
    .buildClient();

ディレクトリ

ディレクトリリソースには、そのディレクトリのプロパティが含まれます。これにより、ディレクトリまたはサブディレクトリまたはファイルの作成、一覧表示、削除、プロパティの取得、メタデータの設定、ハンドルの一覧表示と強制的なクローズの操作が可能になります。 SASToken を取得したら、を使用してファイルサービスクライアントを${accountName}${shareName}${directoryPath}構築できます。${sasToken}

String directoryURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareDirectoryClient directoryClient = new ShareFileClientBuilder().endpoint(directoryURL)
    .sasToken(SAS_TOKEN).shareName(shareName).resourcePath(directoryPath).buildDirectoryClient();

ファイル

ファイルリソースには、そのファイルのプロパティが含まれています。これにより、ファイルまたはファイル範囲の作成、アップロード、コピー、ダウンロード、削除、プロパティの取得、メタデータの設定、ハンドルの一覧表示、強制終了の操作が可能になります。 SASToken を取得したら、を使用してファイルサービスクライアントを${accountName}${shareName}${directoryPath}${fileName}構築できます。${sasToken}

String fileURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareFileClient fileClient = new ShareFileClientBuilder().connectionString(CONNECTION_STRING)
    .endpoint(fileURL).shareName(shareName).resourcePath(directoryPath + "/" + fileName).buildFileClient();

例

次のセクションでは、次のような最も一般的な Configuration Service タスクの一部をカバーするいくつかのコードスニペットを示します。

共有を作成する
共有でスナップショットを作成する
ディレクトリを作成する
サブディレクトリを作成する
ファイルを作成する
すべての共有を一覧表示する
すべてのサブディレクトリとファイルを一覧表示する
ファイル上のすべての範囲を一覧表示する
共有を削除する
ディレクトリを削除する
サブディレクトリを削除する
ファイルを削除する
ファイルをコピーする
ファイルのコピーを中止する
ストレージファイルにデータをアップロードする
4 MB を超えるデータをストレージファイルにアップロードする
ストレージファイルにファイルをアップロードする
ファイル範囲からデータをダウンロードする
ストレージファイルからファイルをダウンロードする
共有サービスのプロパティを取得する
共有サービスのプロパティを設定する
共有メタデータを設定する
共有アクセスポリシーを取得する
共有アクセスポリシーを設定する
ディレクトリとファイルのハンドルを取得する
ハンドル ID にハンドルを強制的に閉じる
共有でクォータを設定する
ファイル httpHeaders を設定する

ストレージアカウントで共有を作成します。共有の作成に失敗した場合は StorageException をスローします。 KeyConcept で ShareServiceClient を取得する( ${shareServiceClient})。

String shareName = "testshare";
shareServiceClient.createShare(shareName);

KeyConcept で ShareServiceClient を取得する( ${shareServiceClient})。

String shareName = "testshare";
ShareClient shareClient = shareServiceClient.getShareClient(shareName);
shareClient.createSnapshot();

ディレクトリを作成する

上で初期化された shareClient を取得します。 ${shareClient}。

String dirName = "testdir";
shareClient.createDirectory(dirName);

サブディレクトリの作成

KeyConcept で directoryClient を取得します。 ${directoryClient}.

String subDirName = "testsubdir";
directoryClient.createSubdirectory(subDirName);

ファイルを作成する

KeyConcept で directoryClient を取得します。 ${directoryClient} .

String fileName = "testfile";
long maxSize = 1024;
directoryClient.createFile(fileName, maxSize);

すべての共有を一覧表示する

KeyConcept で shareServiceClient を取得し、 ${shareServiceClient}

shareServiceClient.listShares();

すべてのサブディレクトリとファイルを一覧表示する

KeyConcept で directoryClient を取得し、 ${directoryClient}

directoryClient.listFilesAndDirectories();

ファイル上のすべての範囲を一覧表示する

KeyConcept で fileClient を取得し、 ${fileClient}

fileClient.listRanges();

KeyConcept で shareClient を取得し、 ${shareClient}

shareClient.delete();

ディレクトリを削除する

KeyConcept で shareClient を取得します ${shareClient} 。。

String dirName = "testdir";
shareClient.deleteDirectory(dirName);

サブディレクトリを削除する

KeyConcept で directoryClient を取得します。 ${directoryClient} .

String subDirName = "testsubdir";
directoryClient.deleteSubdirectory(subDirName);

ファイルを削除する

KeyConcept で directoryClient を取得します。 ${directoryClient} .

String fileName = "testfile";
directoryClient.deleteFile(fileName);

ファイルのコピー

ソース URL の文字列を含む KeyConcept ${fileClient} で fileClient を取得します。

String sourceURL = "https://myaccount.file.core.windows.net/myshare/myfile";
Duration pollInterval = Duration.ofSeconds(2);
SyncPoller<ShareFileCopyInfo, Void> poller = fileClient.beginCopy(sourceURL, (Map<String, String>) null, pollInterval);

ファイルのコピーを中止する

KeyConcept で fileClient を取得し、 ${fileClient} 上記 ${copyId}=[copyInfoResponse](#copy-a-file)のコピー情報応答を返します。

fileClient.abortCopy("copyId");

ストレージにデータをアップロードする

KeyConcept で fileClient を取得し、 ${fileClient} "default" のデータを使用します。

String uploadText = "default";
InputStream data = new ByteArrayInputStream(uploadText.getBytes(StandardCharsets.UTF_8));
fileClient.upload(data, uploadText.length());

4 MB を超えるデータをストレージにアップロードする

KeyConcept で fileClient を取得し、 ${fileClient} "default" のデータを使用します。

byte[] data = "Hello, data sample!".getBytes(StandardCharsets.UTF_8);

long chunkSize = 4 * 1024 * 1024L;
if (data.length > chunkSize) {
    for (int offset = 0; offset < data.length; offset += chunkSize) {
        try {
            // the last chunk size is smaller than the others
            chunkSize = Math.min(data.length - offset, chunkSize);

            // select the chunk in the byte array
            byte[] subArray = Arrays.copyOfRange(data, offset, (int) (offset + chunkSize));

            // upload the chunk
            fileClient.uploadWithResponse(new ByteArrayInputStream(subArray), chunkSize, (long) offset, null, Context.NONE);
        } catch (RuntimeException e) {
            logger.error("Failed to upload the file", e);
            if (Boolean.TRUE.equals(fileClient.exists())) {
                fileClient.delete();
            }
            throw e;
        }
    }
} else {
    fileClient.upload(new ByteArrayInputStream(data), data.length);
}

ストレージにファイルをアップロードする

KeyConcept で fileClient を取得します。 ${fileClient} .

String filePath = "${myLocalFilePath}";
fileClient.uploadFromFile(filePath);

ファイル範囲からデータをダウンロードする

KeyConcept で fileClient を取得し、 ${fileClient} 1024 から 2048 の範囲を指定します。

ShareFileRange fileRange = new ShareFileRange(0L, 2048L);
OutputStream stream = new ByteArrayOutputStream();
fileClient.downloadWithResponse(stream, fileRange, false, null, Context.NONE);

ストレージからファイルをダウンロードする

KeyConcept で fileClient を取得し、 ${fileClient} filePath のファイルにダウンロードします。

String filePath = "${myLocalFilePath}";
fileClient.downloadToFile(filePath);

KeyConcept で ShareServiceClient を取得する( ${shareServiceClient} )。

shareServiceClient.getProperties();

KeyConcept で ShareServiceClient を取得する( ${shareServiceClient} )。

ShareServiceProperties properties = shareServiceClient.getProperties();

properties.getMinuteMetrics().setEnabled(true).setIncludeApis(true);
properties.getHourMetrics().setEnabled(true).setIncludeApis(true);

shareServiceClient.setProperties(properties);

KeyConcept で shareClient を取得します ${shareClient} 。。

Map<String, String> metadata = Collections.singletonMap("directory", "metadata");
shareClient.setMetadata(metadata);

KeyConcept で shareClient を取得します ${shareClient} 。。

shareClient.getAccessPolicy();

KeyConcept で shareClient を取得します ${shareClient} 。。

ShareAccessPolicy accessPolicy = new ShareAccessPolicy().setPermissions("r")
    .setStartsOn(OffsetDateTime.now(ZoneOffset.UTC))
    .setExpiresOn(OffsetDateTime.now(ZoneOffset.UTC).plusDays(10));
ShareSignedIdentifier permission = new ShareSignedIdentifier().setId("mypolicy").setAccessPolicy(accessPolicy);
shareClient.setAccessPolicy(Collections.singletonList(permission));

ディレクトリファイルのハンドルを取得する

KeyConcept で directoryClient を取得し、 ${directoryClient}

PagedIterable<HandleItem> handleItems = directoryClient.listHandles(null, true, Duration.ofSeconds(30), Context.NONE);

ハンドル ID にハンドルを強制的に閉じる

KeyConcept で directoryClient を取得し、 ${directoryClient} 上記で返されたハンドル ID を取得する ${handleId}=[handleItems](#get-handles-on-directory-file)

PagedIterable<HandleItem> handleItems = directoryClient.listHandles(null, true, Duration.ofSeconds(30), Context.NONE);
String handleId = handleItems.iterator().next().getHandleId();
directoryClient.forceCloseHandleWithResponse(handleId, Duration.ofSeconds(30), Context.NONE);

KeyConcept で shareClient を取得します ${shareClient} 。。

int quotaOnGB = 1;
shareClient.setPropertiesWithResponse(new ShareSetPropertiesOptions().setQuotaInGb(quotaOnGB), null, Context.NONE);

ファイル httpheaders を設定する

KeyConcept で fileClient を取得します。 ${fileClient} .

ShareFileHttpHeaders httpHeaders = new ShareFileHttpHeaders().setContentType("text/plain");
fileClient.setProperties(1024, httpHeaders, null, null);

トラブルシューティング

全般

この Java クライアントライブラリを使用してファイルを操作する場合、サービスによって返されるエラーは、 REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。たとえば、ストレージアカウントに存在しない共有を取得しようとすると、 404 を示す Not Foundエラーが返されます。

既定の HTTP クライアント

すべてのクライアントライブラリでは、Netty HTTP クライアントが既定で使用されます。前述の依存関係を追加すると、Netty HTTP クライアントを使用するようにクライアントライブラリが自動的に構成されます。 HTTP クライアントの構成と変更については、HTTP クライアントの Wiki で詳しく説明されています。

既定の SSL ライブラリ

すべてのクライアントライブラリは、Tomcat ネイティブの Boring SSL ライブラリを既定で使用して、SSL 操作にネイティブレベルのパフォーマンスを実現しています。 Boring SSL ライブラリは、Linux、macOS、Windows のネイティブライブラリを含んだ uber jar であり、JDK 内の既定の SSL 実装よりも優れたパフォーマンスを備えています。依存関係のサイズを縮小する方法など、詳細については、Wiki の「パフォーマンスチューニング」セクションを参照してください。

次の手順

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

このリポジトリへの投稿の詳細については、投稿ガイドを参照してください。

フォーク
機能ブランチを作成する (git checkout -b my-new-feature)
変更をコミットする (git commit -am 'Add some feature')
ブランチにプッシュする (git push origin my-new-feature)
新しい Pull Request を作成する

Java 用 Azure File Share クライアント ライブラリ - バージョン 12.20.1

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

ストレージ アカウントを作成する

クライアントを認証する

資格情報の取得

主要な概念

URL 形式

リソースの URI の構文

例外処理

リソース名

［共有名］

ディレクトリ名とファイル名

メタデータ名

サービスの共有

共有

SASToken と共有する

ConnectionString で共有する

共有する TokenCredential

ディレクトリ

ファイル

例

共有を作成する

共有でスナップショットを作成する

ディレクトリを作成する

サブディレクトリの作成

ファイルを作成する

すべての共有を一覧表示する

すべてのサブディレクトリとファイルを一覧表示する

ファイル上のすべての範囲を一覧表示する

共有を削除する

ディレクトリを削除する

サブディレクトリを削除する

ファイルを削除する

ファイルのコピー

ファイルのコピーを中止する

ストレージにデータをアップロードする

4 MB を超えるデータをストレージにアップロードする

ストレージにファイルをアップロードする

ファイル範囲からデータをダウンロードする

ストレージからファイルをダウンロードする

共有サービスのプロパティを取得する

共有サービスのプロパティを設定する

共有メタデータを設定する

共有アクセス ポリシーを取得する

共有アクセス ポリシーを設定する

ディレクトリ ファイルのハンドルを取得する

ハンドル ID にハンドルを強制的に閉じる

共有にクォータを設定する

ファイル httpheaders を設定する

トラブルシューティング

全般

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

共同作成

フィードバック

フィードバック

その他のリソース

Java 用 Azure File Share クライアントライブラリ - バージョン 12.20.1

ストレージアカウントを作成する

共有する `TokenCredential`

共有アクセスポリシーを取得する

共有アクセスポリシーを設定する

ディレクトリファイルのハンドルを取得する