Java 用Azure Container Registry クライアント ライブラリ - バージョン 1.2.2

Azure Container Registryを使用すると、コンテナー イメージと成果物を、すべての種類のコンテナー デプロイのプライベート レジストリに格納および管理できます。

Azure Container Registry のクライアント ライブラリを使用して、次のことを行います。

• レジストリ内のイメージまたは成果物を一覧表示する
• イメージと成果物、リポジトリ、タグのメタデータを取得する
• レジストリ項目の読み取り、書き込み、削除プロパティを設定する
• イメージと成果物、リポジトリ、タグを削除する

ソースコード | パッケージ (Maven) | 製品ドキュメント | サンプル

作業の開始

前提条件

• Java Development Kit (JDK) バージョン 8 以降。
• Azure サブスクリプション
• コンテナー レジストリの作成

パッケージを組み込む

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-containers-containerregistry</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-containers-containerregistry</artifactId>
  <version>1.2.2</version>
</dependency>

クライアントの認証

Azure Identity ライブラリは、認証に対する Azure Active Directory のサポートを簡単に提供します。 以下のすべてのサンプルでは、ログイン サーバーの名前と https:// プレフィックスを含む URL であるエンドポイントがあることを前提としています。 詳細については、Azure Container Registry ポータルを参照してください。

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryAsyncClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildAsyncClient();

Azure Container Registryでの AAD の使用の詳細については、サービスの認証の概要に関するページを参照してください。

ARM AAD トークンを使用した認証

既定では、Container Registry SDK for Java では ACR アクセス トークンが使用されます。 ARM AAD トークンで認証し、対応するポリシーを有効にする場合は、コンテナー レジストリ クライアントをビルドするときに対象ユーザーを設定してください。 ARM 認証ポリシーの構成をチェックする方法については、ACR CLI リファレンスを参照してください。

ContainerRegistryAudience 値はクラウドに固有です。

ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(getEndpoint())
    .credential(credential)
    .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
    .buildClient();

registryClient
    .listRepositoryNames()
    .forEach(name -> System.out.println(name));

各国のクラウド

National Cloud のレジストリで認証を行うには、クライアント構成に次の追加を行う必要があります。

• ID クライアント ライブラリのドキュメントに従って、資格情報ビルダーで をauthorityHost設定します。
• yourcontainer Registry リソースに対して ACR アクセス トークン認証が無効になっている場合は、Container Registry クライアント ビルダーで対象ユーザーを構成する必要があります。

ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(getEndpoint())
    .credential(credential)
    // only if ACR access tokens are disabled or not supported
    .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_CHINA)
    .buildClient();

registryClient
    .listRepositoryNames()
    .forEach(name -> System.out.println(name));

匿名アクセスのサポート

ビルダーが資格情報なしでインスタンス化された場合、SDK は匿名プル モードのサービス クライアントを作成します。 ユーザーは、匿名プルが有効になっているレジストリでこの設定を使用する必要があります。 このモードでは、ユーザーは listRepositoryNames メソッドとそのオーバーロードのみを呼び出すことができます。 他のすべての呼び出しは失敗します。 詳細については、「匿名プル アクセス」を参照してください

ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildClient();

ContainerRegistryAsyncClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildAsyncClient();

主要な概念

レジストリには、Docker イメージと OCI 成果物が格納されます。 イメージまたは成果物は、"マニフェスト"と "レイヤー" で構成されます。 イメージのマニフェストは、画像を構成するレイヤーを記述し、 そのダイジェストによって一意に識別されます。 画像に "タグ付け" して、人間が判読できるエイリアスを付けることもできます。 イメージまたは成果物には 0 個以上の タグ を関連付けることができ、各タグはイメージを一意に識別します。 同じ名前を共有し、異なるタグを持つイメージのコレクションは、 リポジトリと呼ばれます。

詳細については、「 コンテナー レジストリの概念」を参照してください。

例

同期の例

• レジストリ操作:
  • リポジトリ名を一覧表示する
  • 匿名アクセスを使用して成果物タグを一覧表示する
  • 成果物のプロパティを設定する
  • イメージを削除する
  • 匿名アクセス スローを使用してリポジトリを削除する
• BLOB とマニフェストの操作:
  • 画像のアップロード
  • 画像をダウンロードする
  • マニフェストの削除
  • BLOB を削除する

レジストリの操作

このセクションにはサンプルが ContainerRegistryClient 含まれています。

リポジトリ名を一覧表示する

レジストリ内のリポジトリのコレクションを反復処理します。

registryClient.listRepositoryNames().forEach(repository -> System.out.println(repository));

匿名アクセスを使用して成果物タグを一覧表示する

RegistryArtifact image = anonymousClient.getArtifact(repositoryName, digest);

PagedIterable<ArtifactTagProperties> tags = image.listTagProperties();

System.out.printf(String.format("%s has the following aliases:", image.getFullyQualifiedReference()));

for (ArtifactTagProperties tag : tags) {
    System.out.printf(String.format("%s/%s:%s", anonymousClient.getEndpoint(), repositoryName, tag.getName()));
}

成果物のプロパティを設定する

RegistryArtifact image = registryClient.getArtifact(repositoryName, digest);

image.updateTagProperties(
    tag,
    new ArtifactTagProperties()
        .setWriteEnabled(false)
        .setDeleteEnabled(false));

イメージの削除

final int imagesCountToKeep = 3;
for (String repositoryName : registryClient.listRepositoryNames()) {
    final ContainerRepository repository = registryClient.getRepository(repositoryName);

    // Obtain the images ordered from newest to oldest
    PagedIterable<ArtifactManifestProperties> imageManifests =
        repository.listManifestProperties(
            ArtifactManifestOrder.LAST_UPDATED_ON_DESCENDING,
            Context.NONE);

    imageManifests.stream().skip(imagesCountToKeep)
        .forEach(imageManifest -> {
            System.out.printf(String.format("Deleting image with digest %s.%n", imageManifest.getDigest()));
            System.out.printf("    This image has the following tags: ");

            for (String tagName : imageManifest.getTags()) {
                System.out.printf("        %s:%s", imageManifest.getRepositoryName(), tagName);
            }

            repository.getArtifact(imageManifest.getDigest()).delete();
        });
}

匿名アクセス スローを使用してリポジトリを削除する

final String endpoint = getEndpoint();
final String repositoryName = getRepositoryName();

ContainerRegistryClient anonymousClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildClient();

try {
    anonymousClient.deleteRepository(repositoryName);
    System.out.println("Unexpected Success: Delete is not allowed on anonymous access");
} catch (ClientAuthenticationException ex) {
    System.out.println("Expected exception: Delete is not allowed on anonymous access");
}

BLOB とマニフェストの操作

このセクションには、画像を ContainerRegistryContentClient アップロードおよびダウンロードする方法を示す サンプルが含まれています。

まず、BLOB クライアントを作成する必要があります。

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryContentClient contentClient = new ContainerRegistryContentClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .repositoryName(repository)
    .buildClient();

画像のアップロード

完全なイメージをアップロードするには、個々のレイヤーと構成をアップロードする必要があります。 その後、画像または成果物を記述するマニフェストをアップロードし、タグを割り当てることができます。

BinaryData configContent = BinaryData.fromObject(Collections.singletonMap("hello", "world"));

UploadRegistryBlobResult configUploadResult = contentClient.uploadBlob(configContent);
System.out.printf("Uploaded config: digest - %s, size - %s\n", configUploadResult.getDigest(), configContent.getLength());

OciDescriptor configDescriptor = new OciDescriptor()
    .setMediaType("application/vnd.unknown.config.v1+json")
    .setDigest(configUploadResult.getDigest())
    .setSizeInBytes(configContent.getLength());

BinaryData layerContent = BinaryData.fromString("Hello Azure Container Registry");
UploadRegistryBlobResult layerUploadResult = contentClient.uploadBlob(layerContent);
System.out.printf("Uploaded layer: digest - %s, size - %s\n", layerUploadResult.getDigest(), layerContent.getLength());

OciImageManifest manifest = new OciImageManifest()
    .setConfiguration(configDescriptor)
    .setSchemaVersion(2)
    .setLayers(Collections.singletonList(
        new OciDescriptor()
            .setDigest(layerUploadResult.getDigest())
            .setSizeInBytes(layerContent.getLength())
            .setMediaType("application/octet-stream")));

SetManifestResult manifestResult = contentClient.setManifest(manifest, "latest");
System.out.printf("Uploaded manifest: digest - %s\n", manifestResult.getDigest());

イメージのダウンロード

完全なイメージをダウンロードするには、マニフェストをダウンロードし、個々のレイヤーと構成をダウンロードする必要があります。

GetManifestResult manifestResult = contentClient.getManifest("latest");

OciImageManifest manifest = manifestResult.getManifest().toObject(OciImageManifest.class);
System.out.printf("Got manifest:\n%s\n", PRETTY_PRINT.writeValueAsString(manifest));

String configFileName = manifest.getConfiguration().getDigest() + ".json";
contentClient.downloadStream(manifest.getConfiguration().getDigest(), createFileChannel(configFileName));
System.out.printf("Got config: %s\n", configFileName);

for (OciDescriptor layer : manifest.getLayers()) {
    contentClient.downloadStream(layer.getDigest(), createFileChannel(layer.getDigest()));
    System.out.printf("Got layer: %s\n", layer.getDigest());
}

BLOB を削除する

GetManifestResult manifestResult = contentClient.getManifest("latest");

OciImageManifest manifest = manifestResult.getManifest().toObject(OciImageManifest.class);
for (OciDescriptor layer : manifest.getLayers()) {
    contentClient.deleteBlob(layer.getDigest());
}

マニフェストの削除

GetManifestResult manifestResult = contentClient.getManifest("latest");
contentClient.deleteManifest(manifestResult.getDigest());

トラブルシューティング

さまざまな障害シナリオを診断する方法の詳細については、 トラブルシューティング ガイド を参照してください。

次の手順

• さらに azure-containers-containerregistry とサンプルを参照してください
• デモまたは詳細なビデオを見る
• Azure Container Registry サービスの詳細を確認する

共同作成

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

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