すべてのプロダクト
Search

このプロダクト

    Object Storage Service:オブジェクトのメタデータの管理 (Java SDK V1)

    ドキュメントセンター

    Object Storage Service:オブジェクトのメタデータの管理 (Java SDK V1)

    最終更新日:Nov 27, 2025

    Object Storage Service (OSS) に保存されているオブジェクトは、キー、データ、およびオブジェクトのメタデータで構成されます。オブジェクトのメタデータは、オブジェクトの属性を記述するもので、標準 HTTP ヘッダーとユーザーメタデータが含まれます。標準 HTTP ヘッダーを設定して、オブジェクトのキャッシュや強制ダウンロードポリシーなど、カスタムの HTTP リクエストポリシーを作成できます。また、オブジェクトにユーザーメタデータを設定して、その目的や属性を識別することもできます。

    注意事項

    • このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用します。同じリージョン内の他の Alibaba Cloud サービスから OSS にアクセスするには、内部エンドポイントを使用します。サポートされているリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。

    • このトピックでは、アクセス認証情報は環境変数から取得されます。アクセス認証情報の設定方法の詳細については、「アクセス認証情報の設定」をご参照ください。

    • このトピックでは、OSS エンドポイントを使用して OSSClient インスタンスを作成します。カスタムドメイン名またはセキュリティトークンサービス (STS) を使用して OSSClient インスタンスを作成する場合は、「一般的なシナリオの設定例」をご参照ください。

    • オブジェクトのメタデータを設定するには、oss:PutObject 権限が必要です。オブジェクトのメタデータを取得するには、oss:GetObject 権限が必要です。詳細については、「RAM ユーザーへのカスタムポリシーのアタッチ」をご参照ください。

    オブジェクトのメタデータの設定

    次の例では、標準 HTTP ヘッダーとカスタムメタデータを設定する方法を示します。

    • 標準 HTTP ヘッダーの設定

      次のコードは、標準 HTTP ヘッダーを設定する方法を示しています。

      import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.common.utils.BinaryUtil;
import com.aliyun.oss.common.utils.DateUtil;
import com.aliyun.oss.model.ObjectMetadata;
import java.io.ByteArrayInputStream;

public class Demo {
    public static void main(String[] args) throws Exception {
        // 中国 (杭州) リージョンのエンドポイントを例として使用します。実際のエンドポイントを指定してください。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // バケット名を指定します。例：examplebucket。
        String bucketName = "examplebucket";
        // オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めないでください。例：testfolder/exampleobject.txt。
        String objectName = "testfolder/exampleobject.txt";
        String content = "Hello OSS";
        // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になったら、シャットダウンメソッドを呼び出してリソースを解放します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            // アップロードするオブジェクトのメタデータを作成します。
            ObjectMetadata meta = new ObjectMetadata();

            String md5 = BinaryUtil.toBase64String(BinaryUtil.calculateMd5(content.getBytes()));
            // オブジェクトコンテンツの MD5 検証を有効にします。この機能を有効にすると、OSS はアップロードされたオブジェクトの MD5 ハッシュと指定された MD5 ハッシュを比較します。2つのハッシュ値が異なる場合、例外がスローされます。
            meta.setContentMD5(md5);
            // アップロードするオブジェクトのコンテンツタイプを指定します。コンテンツタイプによって、ブラウザがオブジェクトを読み取る方法が決まります。このパラメーターを指定しない場合、コンテンツタイプはオブジェクトのファイル拡張子に基づいて生成されます。オブジェクトにファイル拡張子がない場合、デフォルト値の application/octet-stream が使用されます。
            meta.setContentType("text/plain; charset=utf-8");
            // ヘッダーを設定します。たとえば、アップロードされたオブジェクトのストレージクラスを設定します。
            meta.setHeader("x-oss-storage-class", StorageClass.Standard);
            
            // 必要に応じて、次の行のコメントを解除します。
            
            // ダウンロード時のオブジェクト名を設定します。
            // meta.setContentDisposition("attachment; filename=\"DownloadFilename\"");
            // アップロードするオブジェクトの長さを設定します。オブジェクトがこの長さより大きい場合は切り捨てられます。オブジェクトが小さい場合は、実際の長さが使用されます。
            // meta.setContentLength(content.length());
            // オブジェクトのダウンロード時の Web ページのキャッシュ動作を設定します。
            // meta.setCacheControl("Download Action");
            // キャッシュの有効期限を設定します。時刻は GMT 形式である必要があります。
            // meta.setExpirationTime(DateUtil.parseIso8601Date("2022-10-12T00:00:00.000Z"));
            // ダウンロード時のオブジェクトのエンコード形式を設定します。
            // meta.setContentEncoding("gzip");

            // オブジェクトをアップロードします。
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), meta);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

      HTTP ヘッダーの詳細については、「RFC 2616」をご参照ください。

    • カスタムメタデータの設定

      カスタムメタデータを設定して、オブジェクトを記述できます。

      次のコードは、オブジェクトのカスタムメタデータを設定する方法を示しています。

      import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.ObjectMetadata;
import java.io.ByteArrayInputStream;

public class Demo {
    public static void main(String[] args) throws Exception {
        // 中国 (杭州) リージョンのエンドポイントを例として使用します。実際のエンドポイントを指定してください。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // バケット名を指定します。例：examplebucket。
        String bucketName = "examplebucket";
        // オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めないでください。例：testfolder/exampleobject.txt。
        String objectName = "testfolder/exampleobject.txt";
        String content = "Hello OSS";
        // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になったら、シャットダウンメソッドを呼び出してリソースを解放します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            // オブジェクトのメタデータを作成します。
            ObjectMetadata meta = new ObjectMetadata();
            // カスタムメタデータを設定します。Base64 エンコーディングを使用することを推奨します。
            meta.addUserMetadata("key1", "value1");
            meta.addUserMetadata("key2", "value2");

            // オブジェクトをアップロードします。
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), meta);            
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

      オブジェクトのメタデータは、オブジェクトとともにダウンロードされます。1つのオブジェクトに複数のメタデータエントリを含めることができます。メタデータの合計サイズは 8 KB を超えることはできません。

    オブジェクトのメタデータの変更

    次のコードは、オブジェクトのメタデータを変更する方法を示しています。

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.common.utils.DateUtil;
import com.aliyun.oss.model.CopyObjectRequest;
import com.aliyun.oss.model.ObjectMetadata;

public class Demo {
    public static void main(String[] args) throws Exception {
        // 中国 (杭州) リージョンのエンドポイントを例として使用します。実際のエンドポイントを指定してください。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // ソースバケットの名前を指定します。
        String sourceBucketName = "yourSourceBucketName";
        // ソースオブジェクトの完全なパスを指定します。
        String sourceObjectName = "yourSourceObjectName";
        // 宛先バケットの名前を指定します。宛先バケットはソースバケットと同じリージョンにある必要があります。
        String destinationBucketName = "yourDestinationBucketName";
        // 宛先オブジェクトの完全なパスを指定します。
        String destinationObjectName = "yourDestinationObjectName";
        // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になったら、シャットダウンメソッドを呼び出してリソースを解放します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            // ソースオブジェクトを宛先オブジェクトと同じに設定します。ossClient.copyObject メソッドを呼び出して、オブジェクトのメタデータを変更します。
            CopyObjectRequest request = new CopyObjectRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);

            ObjectMetadata meta = new ObjectMetadata();
            // アップロードするオブジェクトのコンテンツタイプを指定します。コンテンツタイプによって、ブラウザがオブジェクトを読み取る方法が決まります。このパラメーターを指定しない場合、コンテンツタイプはオブジェクトのファイル拡張子に基づいて生成されます。オブジェクトにファイル拡張子がない場合、デフォルト値の application/octet-stream が使用されます。
            meta.setContentType("text/plain; charset=utf-8");
            // ヘッダーを設定します。たとえば、アップロードされたオブジェクトのストレージクラスを設定します。
            meta.setHeader("x-oss-storage-class", StorageClass.Standard);
            
            // 必要に応じて、次の行のコメントを解除します。
            
            // ダウンロード時のオブジェクト名を設定します。
            // meta.setContentDisposition("attachment; filename=\"DownloadFilename\"");
            // アップロードするオブジェクトの長さを設定します。オブジェクトがこの長さより大きい場合は切り捨てられます。オブジェクトが小さい場合は、実際の長さが使用されます。
            // meta.setContentLength(content.length());
            // オブジェクトのダウンロード時の Web ページのキャッシュ動作を設定します。
            // meta.setCacheControl("Download Action");
            // キャッシュの有効期限を設定します。時刻は GMT 形式である必要があります。
            // meta.setExpirationTime(DateUtil.parseIso8601Date("2022-10-12T00:00:00.000Z"));
            // ダウンロード時のオブジェクトのエンコード形式を設定します。
            // meta.setContentEncoding("gzip");            
           
            // カスタムメタデータを設定します。
            meta.addUserMetadata("key1", "value1");
            meta.addUserMetadata("key2", "value2");
            
            request.setNewObjectMetadata(meta);

            // メタデータを変更します。
            ossClient.copyObject(request);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

    オブジェクトのメタデータの取得

    次の 2 つのメソッドを使用して、オブジェクトのメタデータを取得できます。

    メソッド

    説明

    ossClient.getSimplifiedObjectMeta

    オブジェクトの ETag、サイズ、最終更新日時を取得します。このメソッドは、GetObjectMeta API 操作に対応します。

    ossClient.getObjectMetadata

    オブジェクトのすべてのメタデータを取得します。このメソッドは、HeadObject API 操作に対応します。

    次のコードは、オブジェクトのメタデータを取得する方法を示しています。

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.ObjectMetadata;
import com.aliyun.oss.model.SimplifiedObjectMeta;

public class Demo {
    public static void main(String[] args) throws Exception {
        // 中国 (杭州) リージョンのエンドポイントを例として使用します。実際のエンドポイントを指定してください。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // バケット名を指定します。例：examplebucket。
        String bucketName = "examplebucket";
        // オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めないでください。例：testfolder/exampleobject.txt。
        String objectName = "testfolder/exampleobject.txt";
        // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になったら、シャットダウンメソッドを呼び出してリソースを解放します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            // バケット名とオブジェクトの完全なパスを指定します。
            // オブジェクトの部分的なメタデータを取得します。
            SimplifiedObjectMeta objectMeta = ossClient.getSimplifiedObjectMeta(bucketName, objectName);
            System.out.println("Get partial metadata of the object");
            System.out.println(objectMeta.getSize());
            System.out.println(objectMeta.getETag());
            System.out.println(objectMeta.getLastModified());
            // アクセス追跡を有効にすると、最終アクセス時刻 (X-Oss-Last-Access-Time) を含むオブジェクトのメタデータを取得できます。X-Oss-Last-Access-Time は、Java SDK 3.16.0 以降を使用している場合にのみ取得できます。
            System.out.println(objectMeta.getHeaders().get("x-oss-last-access-time"));

            // オブジェクトのすべてのメタデータを取得します。
            ObjectMetadata metadata = ossClient.getObjectMetadata(bucketName, objectName);
            System.out.println("Get all metadata of the object");
            System.out.println(metadata.getContentType());
            System.out.println(metadata.getLastModified());
            System.out.println(metadata.getExpirationTime());
            System.out.println(metadata.getETag());
            System.out.println(metadata.getContentMD5());
            System.out.println(metadata.getContentLength());
            System.out.println(metadata.getObjectType());
            System.out.println(metadata.getUserMetadata());
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

    関連ドキュメント

    • オブジェクトのメタデータの詳細については、「オブジェクトのメタデータの管理」をご参照ください。

    • オブジェクトのメタデータを設定および取得するために使用される完全なサンプルコードについては、GitHub の例をご参照ください。

    • 簡易アップロード中にオブジェクトのメタデータを設定するために呼び出すことができる API 操作の詳細については、「PutObject」をご参照ください。

    • オブジェクトのメタデータを取得するために呼び出すことができる API 操作の詳細については、「GetObjectMeta」および「HeadObject」をご参照ください。