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

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

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

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

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

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

作業の開始

前提条件

パッケージを組み込む

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 個以上のタグを関連付けることができ、各タグはイメージを一意に識別します。同じ名前を共有し、異なるタグを持つイメージのコレクションは、 リポジトリと呼ばれます。

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

例

レジストリの操作

このセクションにはサンプルが 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 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

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

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

クライアントの認証

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

各国のクラウド

匿名アクセスのサポート

主要な概念

例

同期の例

レジストリの操作

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

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

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

イメージの削除

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

BLOB とマニフェストの操作

画像のアップロード

イメージのダウンロード

BLOB を削除する

マニフェストの削除

トラブルシューティング

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

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

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

クライアントの認証

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

各国のクラウド

匿名アクセスのサポート

主要な概念

例

同期の例

レジストリの操作

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

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

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

イメージの削除

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

BLOB とマニフェストの操作

画像のアップロード

イメージのダウンロード

BLOB を削除する

マニフェストの削除

トラブルシューティング

次の手順

共同作成

フィードバック

その他のリソース

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

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