Object Storage Service:OSS Java SDK V1

環境の準備

Java 7 以降をインストールします。java -version コマンドを実行して、Java のバージョンを確認できます。Java がインストールされていない場合、またはバージョンが Java 7 より前の場合は、Java をダウンロードしてください。

SDK のインストール

お使いの環境に基づいてインストール方法を選択してください。OSS Java SDK V1 の最新バージョンを使用することを推奨します。

次の例では、OSS Java SDK V1 3.18.4 を使用します。

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.18.4</version>
</dependency>

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.1</version>
</dependency>
<dependency>
    <groupId>javax.activation</groupId>
    <artifactId>activation</artifactId>
    <version>1.1.1</version>
</dependency>
<!-- 2.3.3 以下 -->
<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>2.3.3</version>
</dependency>

アクセス認証情報の設定

RAM ユーザーのアクセスキーペアを使用してアクセス認証情報を設定します。

1. RAM コンソールで、[永続的な AccessKey ペア] を持つ RAM ユーザーを作成します。 AccessKey ペアを保存し、そのユーザーに AliyunOSSFullAccess 権限を付与します。

2. RAM ユーザーのアクセスキーペアを使用して環境変数を設定します。

   Linux

   1. コマンドラインインターフェイスで次のコマンドを実行して、環境変数設定を ~/.bashrc ファイルに追記します。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

   2. 次のコマンドを実行して変更を適用します。

      source ~/.bashrc

   3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. ターミナルで次のコマンドを実行して、デフォルトのシェルタイプを表示します。

      echo $SHELL

   2. デフォルトのシェルタイプに基づいて、次の操作を実行します。

      Zsh

      1. 次のコマンドを実行して、環境変数設定を ~/.zshrc ファイルに追記します。

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

      2. 次のコマンドを実行して変更を適用します。

         source ~/.zshrc

      3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. 次のコマンドを実行して、環境変数設定を ~/.bash_profile ファイルに追記します。

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

      2. 次のコマンドを実行して変更を適用します。

         source ~/.bash_profile

      3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. CMD で次のコマンドを実行します。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. PowerShell で次のコマンドを実行します。

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

   2. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

クライアントの初期化

次のサンプルコードでは、China (Hangzhou) リージョンのパブリックエンドポイントを使用してクライアントを初期化します。次に、アカウントが所有するすべてのバケットを一覧表示して、セットアップを検証します。リージョンとエンドポイントの完全なリストについては、「リージョンとエンドポイント」をご参照ください。

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

import java.util.List;

/**
 * OSS SDK クイックスタートの例
 * OSS クライアントを初期化し、すべてのバケットを一覧表示する方法を示します
 */
public class Test {

    public static void main(String[] args) {
        // 環境変数からアクセス認証情報を取得します
        String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");

        // OSS のリージョンとエンドポイントを設定します
        String region = "cn-hangzhou";
        String endpoint = "oss-cn-hangzhou.aliyuncs.com";

        // 認証情報プロバイダーを作成します
        DefaultCredentialProvider provider = new DefaultCredentialProvider(accessKeyId, accessKeySecret);

        // クライアントパラメーターを設定します
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // V4 署名アルゴリズムの使用を明示的に宣言します
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);

        // OSS クライアントを初期化します
        OSS ossClient = OSSClientBuilder.create()
                .credentialsProvider(provider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .endpoint(endpoint)
                .build();

        // 現在のユーザーのすべてのバケットを一覧表示します
        List<Bucket> buckets = ossClient.listBuckets();
        System.out.println("Successfully connected to OSS. Buckets under the current account:");

        if (buckets.isEmpty()) {
            System.out.println("No buckets found under the current account.");
        } else {
            for (Bucket bucket : buckets) {
                System.out.println("- " + bucket.getName());
            }
        }

        // リソースを解放します
        ossClient.shutdown();
        System.out.println("OSS client has been shut down.");
    }
}

コードを実行すると、現在のアカウントのすべてのリージョンにあるバケットが次のように表示されます：

Successfully connected to OSS. Buckets under the current account:
- example-bucket
OSS client has been shut down.

クライアント例外 (ClientException)

クライアント例外は、リクエストの構築、送信、またはデータ転送中に発生します。一般的なシナリオは以下のとおりです。

• ネットワーク接続が利用できないため、リクエストをサーバーに送信できません。

• ファイルアップロード中に IO 例外が発生します。

• リクエストタイムアウトや証明書の検証の失敗など、基盤となるネットワーク例外が発生します。

ClientException は、リクエストが OSS サーバーに送信されなかったか、クライアント側の処理中にエラーが発生したことを意味します。 ネットワーク接続とクライアント設定を確認してください。

サーバー例外 (OSSException)

サーバー例外は、リクエストが OSS に到達したものの、拒否されたことを意味します。 OSSException には、次の情報が含まれます。

• 詳細なエラーコードとエラーメッセージが含まれているため、問題を正確に特定できます。

• 一般的なエラーには、SignatureDoesNotMatch、AccessDenied、NoSuchKey などがあります。

• エラーコードに基づいてこれらの例外を処理することで、プログラムの堅牢性とユーザーエクスペリエンスを大幅に向上させることができます。

RAM ユーザーのアクセスキーペアの使用

セキュアな環境で、頻繁な認証情報のローテーションを行わずに OSS へ長期アクセスする必要があるアプリケーションに適しています。RAM ユーザーのアクセスキーペア (AccessKey ID と AccessKey シークレット) を使用して認証情報プロバイダーを初期化します。この方法では、アクセスキーペアを手動でメンテナンスする必要があるため、セキュリティリスクが高まります。

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProvider;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;

public class AkDemoTest {
    public static void main(String[] args) throws Exception {
        // RAM ユーザーの AccessKey ID と AccessKey シークレットを入力します。
        String accessKeyId = "yourAccessKeyID";
        String accessKeySecret = "yourAccessKeySecret";
        
        // DefaultCredentialProvider メソッドを使用して、AccessKey ID と AccessKey シークレットを直接設定します。
        CredentialsProvider credentialsProvider = new DefaultCredentialProvider(accessKeyId, accessKeySecret);

        // credentialsProvider を使用してクライアントを初期化します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // V4 署名アルゴリズムの使用を明示的に宣言します。
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してリソースを解放してください。
        OSS ossClient = OSSClientBuilder.create()
                .endpoint("endpoint")
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region("region")
                .build();

        ossClient.shutdown();

    }
}

STS トークンの使用

OSS への一時的なアクセスを必要とするアプリケーションに適しています。STS から取得した一時的な認証情報 (AccessKey ID、AccessKey シークレット、セキュリティトークン) を使用して認証情報プロバイダーを初期化します。繰り返しアクセスする場合は、STS トークンを手動で更新する必要があります。

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProvider;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;

public class StsDemoTest {
    public static void main(String[] args) throws Exception {
        // RAM ユーザーの認証情報ではなく、STS サービスから取得した一時的な AccessKey ID、AccessKey シークレット、セキュリティトークンを設定してください。
        // STS サービスから取得する AccessKey ID は、以下のように「STS」で始まります。
        String accessKeyId = "STS.****************";
        String accessKeySecret = "yourAccessKeySecret";
        String stsToken= "yourSecurityToken";

        // DefaultCredentialProvider メソッドを使用して、AccessKey ID、AccessKey シークレット、およびセキュリティトークンを直接設定します。
        CredentialsProvider credentialsProvider = new DefaultCredentialProvider(accessKeyId, accessKeySecret, stsToken);

        // credentialsProvider を使用してクライアントを初期化します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // V4 署名アルゴリズムを使用することを明示的に宣言します。
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してリソースを解放してください。
        OSS ossClient = OSSClientBuilder.create()
                .endpoint("endpoint")
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region("region")
                .build();

        ossClient.shutdown();
    }
}

RAMRoleARN の使用

クロスアカウントアクセスなど、OSS への承認されたアクセスを必要とするアプリケーションに適しています。RAM ロールの ARN を指定して認証情報プロバイダーを初期化します。SDK は AssumeRole API を呼び出すことで、STS トークンを自動的に取得および更新します。policy パラメーターを使用して、RAM ロールの権限をより限定的にすることもできます。

1. credentials 依存関係を追加します。

   <!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>credentials-java</artifactId>
       <version>LATEST</version>
   </dependency>

2. アクセスキーペアと RAMRoleARN をアクセス認証情報として設定します。

   import com.aliyun.credentials.models.CredentialModel;
   import com.aliyun.oss.ClientBuilderConfiguration;
   import com.aliyun.oss.OSS;
   import com.aliyun.oss.OSSClientBuilder;
   import com.aliyun.oss.common.auth.Credentials;
   import com.aliyun.oss.common.auth.CredentialsProvider;
   import com.aliyun.oss.common.auth.DefaultCredentials;
   import com.aliyun.oss.common.comm.SignVersion;
   
   public class RamRoleArnAkDemoTest {
   
       public static void main(String[] args) {
   
           com.aliyun.credentials.models.Config config = new com.aliyun.credentials.models.Config();
           // アクセス認証情報のタイプ。ram_role_arn に設定します。
           config.setType("ram_role_arn");
           // 引き受ける RAM ロールの ARN。例: acs:ram::123456789012****:role/adminrole。RoleArn は ALIBABA_CLOUD_ROLE_ARN 環境変数を介して設定できます。
           config.setRoleArn("<RoleArn>");
           // 環境変数からアクセスキー ID を取得します。
           config.setAccessKeyId(System.getenv().get("ALIBABA_CLOUD_ACCESS_KEY_ID"));
           // 環境変数からシークレットアクセスキーを取得します。
           config.setAccessKeySecret(System.getenv().get("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
           // ロールセッション名。RoleSessionName は ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数を介して設定できます。
           config.setRoleName("<RoleSessionName>");
           // 権限ポリシーを設定します。これはオプションです。例として、以下のポリシーはすべてのリソースに対するフルアクセス権限を付与します: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
           config.setPolicy("<Policy>");
           // ロールセッションの有効期間を設定します。これはオプションです。
           config.setRoleSessionExpiration(3600);
   
           final com.aliyun.credentials.Client credentialsClient = new com.aliyun.credentials.Client(config);
   
           CredentialsProvider credentialsProvider = new CredentialsProvider(){
               @Override
               public void setCredentials(Credentials credentials) {
               }
   
               @Override
               public Credentials getCredentials() {
                   CredentialModel credential = credentialsClient.getCredential();
                   return  new DefaultCredentials(credential.getAccessKeyId(), credential.getAccessKeySecret(), credential.getSecurityToken());
               }
           };
           // credentialsProvider を使用してクライアントを初期化します。
           ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
           // V4 署名アルゴリズムの使用を明示的に宣言します。
           clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
           // OSSClient インスタンスを作成します。
           // OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してリソースを解放してください。
           OSS ossClient = OSSClientBuilder.create()
                   .endpoint("endpoint")
                   .credentialsProvider(credentialsProvider)
                   .clientConfiguration(clientBuilderConfiguration)
                   .region("region")
                   .build();
   
           ossClient.shutdown();
       }
   }

ECSRAMRole の使用

ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes (ACK) のワーカーノード上のアプリケーションに適しています。RAM ロールをインスタンスにアタッチすることで、手動での認証情報管理なしで、ACK または ECS 内で STS トークンが自動的に取得および更新されます。ECSRAMRole を取得するには、「RAM ロールの作成」をご参照ください。ロールをアタッチするには、「インスタンス RAM ロール」をご参照ください。

1. credentials の依存関係を追加します。

   <!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>credentials-java</artifactId>
       <version>LATEST</version>
   </dependency>

2. ECSRAMRole をアクセス認証情報として設定します。

   import com.aliyun.credentials.models.CredentialModel;
   import com.aliyun.oss.ClientBuilderConfiguration;
   import com.aliyun.oss.OSS;
   import com.aliyun.oss.OSSClientBuilder;
   import com.aliyun.oss.common.auth.Credentials;
   import com.aliyun.oss.common.auth.CredentialsProvider;
   import com.aliyun.oss.common.auth.DefaultCredentials;
   import com.aliyun.oss.common.comm.SignVersion;
   
   public class EcsRamRoleDemoTest {
       public static void main(String[] args) {
   
           com.aliyun.credentials.models.Config config = new com.aliyun.credentials.models.Config();
           // アクセス認証情報のタイプを ecs_ram_role に設定します。
           config.setType("ecs_ram_role");
           // ECS インスタンスに割り当てられた RAM ロールの名前。
           config.setRoleName("<RoleName>");
   
           final com.aliyun.credentials.Client credentialsClient = new com.aliyun.credentials.Client(config);
   
           CredentialsProvider credentialsProvider = new CredentialsProvider(){
               @Override
               public void setCredentials(Credentials credentials) {
               }
   
               @Override
               public Credentials getCredentials() {
                   CredentialModel credential = credentialsClient.getCredential();
                   return  new DefaultCredentials(credential.getAccessKeyId(), credential.getAccessKeySecret(), credential.getSecurityToken());
               }
           };
           // credentialsProvider を使用してクライアントを初期化します。
           ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
           // V4 署名アルゴリズムの使用を明示的に宣言します。
           clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
           // OSSClient インスタンスを作成します。
           // OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してリソースを解放してください。
           OSS ossClient = OSSClientBuilder.create()
                   .endpoint("endpoint")
                   .credentialsProvider(credentialsProvider)
                   .clientConfiguration(clientBuilderConfiguration)
                   .region("region")
                   .build();
   
           ossClient.shutdown();
       }
   }

OIDCRoleARN の使用

Container Service for Kubernetes (ACK) でワーカーノードの RAM ロールを設定すると、対応するノード上のポッド内のアプリケーションは、ECS にデプロイされたアプリケーションと同様に、グローバルメタサービスを介してアタッチされたロールの STS トークンを取得できます。ただし、信頼できないアプリケーションがコンテナクラスターにデプロイされている場合 (例えば、お客様から提供された、コードが公開されていないアプリケーション)、これらのアプリケーションがグローバルメタサービスを介してワーカーノードにアタッチされたインスタンス RAM ロールの STS トークンを取得することを望まない場合があります。クラウドリソースのセキュリティに影響を与えることなく、これらの信頼できないアプリケーションが必要な STS トークンを安全に取得し、アプリケーションレベルでの権限の最小化を実現できるようにするには、サービスアカウント用の RAM ロール (RRSA) 機能を使用できます。この方法の基盤となる実装は STS トークンに基づいています。Alibaba Cloud コンテナクラスターは、異なるアプリケーションポッドに対応するサービスアカウント OIDC トークンファイルを作成してマウントし、関連する設定情報を環境変数に設定します。SDK は、環境変数からの設定情報を使用して STS サービスの AssumeRoleWithOIDC API を呼び出すことで、バインドされたロールの STS トークンを取得します。この方法では、AccessKey ペアまたは STS トークンを提供する必要がないため、手動でこれらを管理するリスクがなくなります。詳細については、「RRSA を使用してサービスアカウントに RAM 権限を設定し、ポッドの権限分離を実現する」をご参照ください。

1. credentials 依存関係を追加します。

   <!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>credentials-java</artifactId>
       <version>LATEST</version>
   </dependency>

2. OIDC RAM ロールをアクセス認証情報として設定します。

   import com.aliyun.credentials.models.CredentialModel;
   import com.aliyun.oss.ClientBuilderConfiguration;
   import com.aliyun.oss.OSS;
   import com.aliyun.oss.OSSClientBuilder;
   import com.aliyun.oss.common.auth.Credentials;
   import com.aliyun.oss.common.auth.CredentialsProvider;
   import com.aliyun.oss.common.auth.DefaultCredentials;
   import com.aliyun.oss.common.comm.SignVersion;
   
   public class OidcRoleArnDemoTest {
       public static void main(String[] args) {
   
           com.aliyun.credentials.models.Config config = new com.aliyun.credentials.models.Config();
           // 認証情報のタイプを oidc_role_arn に設定します。
           config.setType("oidc_role_arn");
           // RAM ロールの ARN。RoleArn は ALIBABA_CLOUD_ROLE_ARN 環境変数を使用して設定できます。
           config.setRoleArn("<RoleArn>");
           // OIDC プロバイダーの ARN。OidcProviderArn は ALIBABA_CLOUD_OIDC_PROVIDER_ARN 環境変数を使用して設定できます。
           config.setOidcProviderArn("<OidcProviderArn>");
           // OIDC トークンファイルへのパス。OidcTokenFilePath は ALIBABA_CLOUD_OIDC_TOKEN_FILE 環境変数を使用して設定できます。
           config.setOidcTokenFilePath("<OidcTokenFilePath>");
           // ロールセッションの名前。RoleSessionName は ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数を使用して設定できます。
           config.setRoleSessionName("<RoleSessionName>");
           // より限定的な権限ポリシーを設定します。これはオプションです。例：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
           config.setPolicy("<Policy>");
           // セッションの有効期限を設定します。
           config.setRoleSessionExpiration(3600);
   
           final com.aliyun.credentials.Client credentialsClient = new com.aliyun.credentials.Client(config);
   
           CredentialsProvider credentialsProvider = new CredentialsProvider(){
               @Override
               public void setCredentials(Credentials credentials) {
               }
   
               @Override
               public Credentials getCredentials() {
                   CredentialModel credential = credentialsClient.getCredential();
                   return  new DefaultCredentials(credential.getAccessKeyId(), credential.getAccessKeySecret(), credential.getSecurityToken());
               }
           };
           // credentialsProvider を使用してクライアントを初期化します。
           ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
           // V4 署名アルゴリズムの使用を明示的に宣言します。
           clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
           // OSSClient インスタンスを作成します。
           // OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してリソースを解放してください。
           OSS ossClient = OSSClientBuilder.create()
                   .endpoint("endpoint")
                   .credentialsProvider(credentialsProvider)
                   .clientConfiguration(clientBuilderConfiguration)
                   .region("region")
                   .build();
   
           ossClient.shutdown();
       }
   }

Function Compute コンテキストからの認証情報の使用

この方法は、Function Compute にデプロイされたアプリケーションの関数向けです。Function Compute コンテキストからの認証情報を使用して認証情報プロバイダーを初期化できます。内部実装は STS トークンに基づいています。Function Compute は、関数に設定されたサービスロールを引き受けることで STS トークンを取得し、コンテキストの Credentials パラメーターを介してその STS トークンをアプリケーションに渡します。この STS トークンは 36 時間有効で、変更できません。関数の最大実行時間は 24 時間であるため、STS トークンは関数の実行中に期限切れになることはなく、更新を考慮する必要はありません。この方法では、AccessKey ペアまたは STS トークンを提供する必要がないため、手動でこれらを管理するリスクがなくなります。Function Compute に OSS へのアクセス権限を付与するには、関数ロールを使用して Function Compute に他の Alibaba Cloud サービスへのアクセス権限を付与するをご参照ください。

1. Function Compute コンテキストの依存関係を追加します。

   <!-- https://mvnrepository.com/artifact/com.aliyun.fc.runtime/fc-java-core -->
   <dependency>
       <groupId>com.aliyun.fc.runtime</groupId>
       <artifactId>fc-java-core</artifactId>
       <version>1.4.1</version>
   </dependency>

2. Function Compute コンテキストからの認証情報を使用して認証情報プロバイダーを初期化します。

   import java.io.IOException;
   import java.io.InputStream;
   import java.io.OutputStream;
   
   import com.aliyun.fc.runtime.Context;
   import com.aliyun.fc.runtime.Credentials;
   import com.aliyun.fc.runtime.StreamRequestHandler;
   import com.aliyun.oss.ClientBuilderConfiguration;
   import com.aliyun.oss.OSS;
   import com.aliyun.oss.OSSClientBuilder;
   import com.aliyun.oss.common.auth.*;
   import com.aliyun.oss.common.comm.SignVersion;
   
   public class App implements StreamRequestHandler {
   
       @Override
       public void handleRequest(
           InputStream inputStream, OutputStream outputStream, Context context) throws IOException {
   
           // 認証情報を取得します。実行前に、関数が属するサービスにロールが設定され、そのロールに必要な OSS 権限が付与されていることを確認してください。AliyunFCDefaultRole ロールを使用することを推奨します。
           Credentials creds = context.getExecutionCredentials();
   
           // 取得した認証情報を使用して認証情報プロバイダーインスタンスを作成します。
           CredentialsProvider credentialsProvider = new DefaultCredentialProvider(creds.getAccessKeyId(), creds.getAccessKeySecret(), creds.getSecurityToken());
   
           // credentialsProvider を使用してクライアントを初期化します。
           ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
           // V4 署名アルゴリズムの使用を明示的に宣言します。
           clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
           // OSSClient インスタンスを作成します。
           // OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してリソースを解放してください。
           OSS ossClient = OSSClientBuilder.create()
                   .endpoint("endpoint")
                   .credentialsProvider(credentialsProvider)
                   .clientConfiguration(clientBuilderConfiguration)
                   .region("region")
                   .build();
   
           ossClient.shutdown();
   
           outputStream.write(new String("done").getBytes());
       }
   }

CredentialsURI の使用

柔軟な認証情報管理のために外部システムから認証情報を取得するアプリケーションに適しています。STS トークンを返す URI を使用して、認証情報プロバイダーを初期化します。SDK は、指定された URI からトークンを自動的に取得し、更新します。

1. SDK が STS トークンを正しく解析して使用するためには、URI が次のレスポンスプロトコルに従う必要があります：

   • レスポンスステータスコード： 200

   • レスポンスボディの構造：

     {
         "Code": "Success",
         "AccessKeySecret": "AccessKeySecret",
         "AccessKeyId": "AccessKeyId",
         "Expiration": "2021-09-26T03:46:38Z",
         "SecurityToken": "SecurityToken"
     }

2. 認証情報の依存関係を追加します。

   <!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>credentials-java</artifactId>
       <version>LATEST</version>
   </dependency>

3. CredentialsURI をアクセス認証情報として設定します。

   import com.aliyun.credentials.models.CredentialModel;
   import com.aliyun.oss.ClientBuilderConfiguration;
   import com.aliyun.oss.OSS;
   import com.aliyun.oss.OSSClientBuilder;
   import com.aliyun.oss.common.auth.Credentials;
   import com.aliyun.oss.common.auth.CredentialsProvider;
   import com.aliyun.oss.common.auth.DefaultCredentials;
   import com.aliyun.oss.common.comm.SignVersion;
   
   public class CredentialsUriDemoTest {
       public static void main(String[] args) {
   
           com.aliyun.credentials.models.Config config = new com.aliyun.credentials.models.Config();
           // アクセス認証情報のタイプ。`credentials_uri` に設定します。
           config.setType("credentials_uri");
           // 認証情報の URI。STS トークンを生成するサーバーのアドレスで、`http://local_or_remote_uri/` という形式です。`CredentialsURI` は `ALIBABA_CLOUD_CREDENTIALS_URI` 環境変数で設定することもできます。
           config.setCredentialsUri("<CredentialsUri>");
   
           final com.aliyun.credentials.Client credentialsClient = new com.aliyun.credentials.Client(config);
   
           CredentialsProvider credentialsProvider = new CredentialsProvider(){
               @Override
               public void setCredentials(Credentials credentials) {
               }
   
               @Override
               public Credentials getCredentials() {
                   CredentialModel credential = credentialsClient.getCredential();
                   return  new DefaultCredentials(credential.getAccessKeyId(), credential.getAccessKeySecret(), credential.getSecurityToken());
               }
           };
           // `credentialsProvider` を使用してクライアントを初期化します。
           ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
           // V4 署名アルゴリズムの使用を明示的に宣言します。
           clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
           // `OSSClient` インスタンスを作成します。
           // `OSSClient` インスタンスが不要になったら、`shutdown` メソッドを呼び出してリソースを解放します。
           OSS ossClient = OSSClientBuilder.create()
                   .endpoint("endpoint")
                   .credentialsProvider(credentialsProvider)
                   .clientConfiguration(clientBuilderConfiguration)
                   .region("region")
                   .build();
   
           ossClient.shutdown();
       }
   }

AccessKey ペアの自動ローテーションの使用

AccessKey の漏洩リスクがある環境で、OSS への長期アクセスを必要とするアプリケーションに適しています。ClientKey を使用して認証情報プロバイダーを初期化します。KMS は、マネージド RAM ユーザーの AccessKey ペアを自動的にローテーションし、静的認証情報を動的化して漏洩リスクを低減します。KMS は即時ローテーションもサポートしています。ClientKey を取得するには、「アプリケーションアクセスポイントの作成」をご参照ください。

1. 認証情報クライアントの依存関係を追加します。

   <!-- https://mvnrepository.com/artifact/com.aliyun/alibabacloud-secretsmanager-client -->
   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>alibabacloud-secretsmanager-client</artifactId>
       <version>1.3.7</version>
   </dependency>
   <!-- https://mvnrepository.com/artifact/com.aliyun/aliyun-java-sdk-core -->
   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>aliyun-java-sdk-core</artifactId>
       <version>4.7.0</version>
   </dependency>

2. 設定ファイル secretsmanager.properties を作成します。

   # アクセス認証情報のタイプ。client_key に固定
   # ClientKey 読み取り用の復号化パスワード：環境変数またはファイルからの読み取りをサポート。いずれか一方のみを設定する必要があります
   client_key_password_from_env_variable=<your client key private key password environment variable name>
   client_key_password_from_file_path=<your client key private key password file path>
   
   # ClientKey の秘密鍵ファイルへのパス
   client_key_private_key_path=<your client key private key file path>
   
   # 関連付けられた KMS サービスのリージョン
   cache_client_region_id=[{"regionId":"<regionId>"}]

3. 設定ファイルを使用して認証情報を渡します。

   import com.aliyun.oss.ClientBuilderConfiguration;
   import com.aliyun.oss.OSS;
   import com.aliyun.oss.OSSClientBuilder;
   import com.aliyun.oss.common.auth.Credentials;
   import com.aliyun.oss.common.auth.CredentialsProvider;
   import com.aliyun.oss.common.auth.DefaultCredentials;
   import com.aliyun.oss.common.comm.SignVersion;
   import com.aliyuncs.kms.secretsmanager.client.SecretCacheClient;
   import com.aliyuncs.kms.secretsmanager.client.SecretCacheClientBuilder;
   import com.aliyuncs.kms.secretsmanager.client.exception.CacheSecretException;
   import com.aliyuncs.kms.secretsmanager.client.model.SecretInfo;
   import org.codehaus.jettison.json.JSONException;
   import org.codehaus.jettison.json.JSONObject;
   
   public class ClientKeyDemoTest {
       public static void main(String[] args) throws CacheSecretException {
           final SecretCacheClient client = SecretCacheClientBuilder.newClient();
           CredentialsProvider credentialsProvider = new CredentialsProvider() {
               @Override
               public void setCredentials(Credentials credentials) {
               }
   
               @Override
               public Credentials getCredentials() {
                   try {
                       SecretInfo secretInfo = client.getSecretInfo("<secretName>");
                       JSONObject jsonObject = new JSONObject(secretInfo.getSecretValue());
   
                       String accessKeyId = jsonObject.getString("AccessKeyId");
                       String accessKeySecret = jsonObject.getString("AccessKeySecret");
   
                       return new DefaultCredentials(accessKeyId, accessKeySecret);
                   } catch (CacheSecretException | JSONException e) {
                       return null;
                   }
               }
           };
           // credentialsProvider を使用してクライアントを初期化します。
           ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
           // V4 署名アルゴリズムの使用を明示的に宣言します。
           clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
           // OSSClient インスタンスを作成します。
           // OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してリソースを解放してください。
           OSS ossClient = OSSClientBuilder.create()
                   .endpoint("endpoint")
                   .credentialsProvider(credentialsProvider)
                   .clientConfiguration(clientBuilderConfiguration)
                   .region("region")
                   .build();
   
           ossClient.shutdown();
       }
   }
   

カスタムアクセス認証情報の使用

上記のいずれの認証情報の設定方法も要件を満たさない場合、Credential Providers インターフェイスを実装することで、認証情報プロバイダーをカスタマイズできます。基盤となる実装が STS トークンに基づいている場合は、認証情報の更新をサポートする必要がある点にご注意ください。

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.Credentials;
import com.aliyun.oss.common.auth.CredentialsProvider;
import com.aliyun.oss.common.auth.DefaultCredentials;
import com.aliyun.oss.common.comm.SignVersion;

public class CustomCredentialProviderDemoTest {

    public static void main(String[] args) {

        CredentialsProvider credentialsProvider = new CredentialsProvider(){

            // 変数を初期化します
            String accessKeyId = null;
            // 変数を初期化します
            String accessKeySecret = null;
            // 変数を初期化します
            // String token = null;

            @Override
            public void setCredentials(Credentials credentials) {
            }

            @Override
            public Credentials getCredentials() {
                // TODO
                // アクセス認証情報を取得するメソッドをカスタマイズします。

                // 長期的な認証情報を返します: access_key_id, access_key_secret  
                return new DefaultCredentials(accessKeyId, accessKeySecret);

                // 一時的な認証情報を返します: access_key_id, access_key_secret, token
                // 一時的な認証情報の場合、有効期限に基づいて更新する必要があります。
                // return new DefaultCredentials(accessKeyId, accessKeySecret, token);
            }
        };
        // credentialsProvider を使用してクライアントを初期化します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // V4 署名アルゴリズムの使用を明示的に宣言します。
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してリソースを解放してください。
        OSS ossClient = OSSClientBuilder.create()
                .endpoint("endpoint")
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region("region")
                .build();

        ossClient.shutdown();
    }
}

デフォルトの認証情報チェーンの使用

パラメーターなしで認証情報クライアントを初期化すると、credentials-java SDK はデフォルトの認証情報チェーンを使用します。認証情報チェーンのロジックについては、「デフォルトの認証情報チェーン」をご参照ください。

1. 認証情報の依存関係を追加します。

   <!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>credentials-java</artifactId>
       <version>LATEST</version>
   </dependency>

2. Credentials をアクセス認証情報として設定します。

   import com.aliyun.credentials.models.CredentialModel;
   import com.aliyun.oss.*;
   import com.aliyun.oss.common.auth.Credentials;
   import com.aliyun.oss.common.auth.CredentialsProvider;
   import com.aliyun.oss.common.auth.DefaultCredentials;
   import com.aliyun.oss.common.comm.SignVersion;
   
   public class Demo {
       public static void main(String[] args) {
           com.aliyun.credentials.Client credentialsClient = new com.aliyun.credentials.Client();
           CredentialsProvider credentialsProvider = new CredentialsProvider(){
               @Override
               public void setCredentials(Credentials credentials) {
               }
   
               @Override
               public Credentials getCredentials() {
                   CredentialModel credential = credentialsClient.getCredential();
                   return  new DefaultCredentials(credential.getAccessKeyId(), credential.getAccessKeySecret(), credential.getSecurityToken());
               }
           };
           ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
           // V4 署名アルゴリズムの使用を明示的に宣言します。
           clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);  
           // credentialsProvider を使用してクライアントを初期化します。
           // OSSClient インスタンスを作成します。
           // OSSClient インスタンスが不要になったら、shutdown メソッドを呼び出してリソースを解放します。
           OSS ossClient = OSSClientBuilder.create()
                   .endpoint("endpoint")
                   .credentialsProvider(credentialsProvider)
                   .clientConfiguration(clientBuilderConfiguration)
                   .region("region")
                   .build();
           ossClient.shutdown();
       }
   }

パッケージの競合

• 原因

  OSS Java SDK V1 を使用する際、以下のようなエラーはプロジェクト内のパッケージの競合を示します。

  Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/http/ssl/TrustStrategy
      at com.aliyun.oss.OSSClient.<init>(OSSClient.java:268)
      at com.aliyun.oss.OSSClient.<init>(OSSClient.java:193)
      at com.aliyun.oss.demo.HelloOSS.main(HelloOSS.java:77)
  Caused by: java.lang.ClassNotFoundException: org.apache.http.ssl.TrustStrategy
      at java.net.URLClassLoader$1.run(URLClassLoader.java:366)
      at java.net.URLClassLoader$1.run(URLClassLoader.java:355)
      at java.security.AccessController.doPrivileged(Native Method)
      at java.net.URLClassLoader.findClass(URLClassLoader.java:354)
      at java.lang.ClassLoader.loadClass(ClassLoader.java:425)
      at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)
      at java.lang.ClassLoader.loadClass(ClassLoader.java:358)
      ... 3 more
                      

  または

  Exception in thread "main" java.lang.NoSuchFieldError: INSTANCE
   at org.apache.http.impl.io.DefaultHttpRequestWriterFactory.<init>(DefaultHttpRequestWriterFactory.java:52)
   at org.apache.http.impl.io.DefaultHttpRequestWriterFactory.<init>(DefaultHttpRequestWriterFactory.java:56)
   at org.apache.http.impl.io.DefaultHttpRequestWriterFactory.<clinit>(DefaultHttpRequestWriterFactory.java:46)
   at org.apache.http.impl.conn.ManagedHttpClientConnectionFactory.<init>(ManagedHttpClientConnectionFactory.java:82)
   at org.apache.http.impl.conn.ManagedHttpClientConnectionFactory.<init>(ManagedHttpClientConnectionFactory.java:95)
   at org.apache.http.impl.conn.ManagedHttpClientConnectionFactory.<init>(ManagedHttpClientConnectionFactory.java:104)
   at org.apache.http.impl.conn.ManagedHttpClientConnectionFactory.<clinit>(ManagedHttpClientConnectionFactory.java:62)
   at org.apache.http.impl.conn.PoolingHttpClientConnectionManager$InternalConnectionFactory.<init>(PoolingHttpClientConnectionManager.java:572)
   at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.<init>(PoolingHttpClientConnectionManager.java:174)
   at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.<init>(PoolingHttpClientConnectionManager.java:158)
   at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.<init>(PoolingHttpClientConnectionManager.java:149)
   at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.<init>(PoolingHttpClientConnectionManager.java:125)
   at com.aliyun.oss.common.comm.DefaultServiceClient.createHttpClientConnectionManager(DefaultServiceClient.java:237)
   at com.aliyun.oss.common.comm.DefaultServiceClient.<init>(DefaultServiceClient.java:78)
   at com.aliyun.oss.OSSClient.<init>(OSSClient.java:268)
   at com.aliyun.oss.OSSClient.<init>(OSSClient.java:193)
   at OSSManagerImpl.upload(OSSManagerImpl.java:42)
   at OSSManagerImpl.main(OSSManagerImpl.java:63)
                      

  このエラーは、OSS Java SDK V1 が Apache HttpClient 4.4.1 を使用しているのに対し、プロジェクトが競合するバージョンの Apache HttpClient または commons-httpclient JAR パッケージを使用しているために発生します。プロジェクトディレクトリで mvn dependency:tree コマンドを実行すると、プロジェクトが使用している JAR パッケージとそのバージョンを確認できます。次の図に示すように、プロジェクトは Apache HttpClient 4.3 を使用しており、これは標準バージョンと競合しています。

  

• 解決策

  次のいずれかの方法でパッケージの競合を解決できます。

  • バージョンの統一：プロジェクトが Apache HttpClient 4.4.1 と競合するバージョンを使用している場合は、プロジェクトを更新してバージョン 4.4.1 を使用し、pom.xml ファイルから他のバージョンの Apache HttpClient への依存関係を削除してください。プロジェクトが commons-httpclient を使用している場合も、競合が存在する可能性があります。commons-httpclient の依存関係を削除してください。

  • 依存関係の競合の解決：プロジェクトが複数のサードパーティパッケージに依存し、さらにそれらのパッケージが異なるバージョンの Apache HttpClient に依存している場合、プロジェクトで依存関係の競合が発生します。exclusion タグを使用して解決できます。詳細については、「Maven ガイド」をご参照ください。

  OSS Java SDK V1 は、以下のパッケージバージョンに依存しています。競合解決の方法は HttpClient の場合と同様です。

  

パッケージの欠落

• 原因

  OSS Java SDK V1 を使用する際、以下のようなエラーは、プロジェクトに OSS Java SDK V1 のコンパイルまたは実行に必要なパッケージが欠落している可能性があることを示します。

  Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/http/auth/Credentials
          at com.aliyun.oss.OSSClient.<init>(OSSClient.java:268)
          at com.aliyun.oss.OSSClient.<init>(OSSClient.java:193)
          at com.aliyun.oss.demo.HelloOSS.main(HelloOSS.java:76)
  Caused by: java.lang.ClassNotFoundException: org.apache.http.auth.Credentials
          at java.net.URLClassLoader$1.run(URLClassLoader.java:366)
          at java.net.URLClassLoader$1.run(URLClassLoader.java:355)
          at java.security.AccessController.doPrivileged(Native Method)
          at java.net.URLClassLoader.findClass(URLClassLoader.java:354)
          at java.lang.ClassLoader.loadClass(ClassLoader.java:425)
          at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)
          at java.lang.ClassLoader.loadClass(ClassLoader.java:358)
          ... 3 more
                      

  または

  Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/http/protocol/HttpContext
          at com.aliyun.oss.OSSClient.<init>(OSSClient.java:268)
          at com.aliyun.oss.OSSClient.<init>(OSSClient.java:193)
          at com.aliyun.oss.demo.HelloOSS.main(HelloOSS.java:76)
  Caused by: java.lang.ClassNotFoundException: org.apache.http.protocol.HttpContext
          at java.net.URLClassLoader$1.run(URLClassLoader.java:366)
          at java.net.URLClassLoader$1.run(URLClassLoader.java:355)
          at java.security.AccessController.doPrivileged(Native Method)
          at java.net.URLClassLoader.findClass(URLClassLoader.java:354)
          at java.lang.ClassLoader.loadClass(ClassLoader.java:425)
          at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)
          at java.lang.ClassLoader.loadClass(ClassLoader.java:358)
          ... 3 more
                      

  または

  Exception in thread "main" java.lang.NoClassDefFoundError: org/jdom/input/SAXBuilder
          at com.aliyun.oss.internal.ResponseParsers.getXmlRootElement(ResponseParsers.java:645)
          at … … 
          at com.aliyun.oss.OSSClient.doesBucketExist(OSSClient.java:471)
          at com.aliyun.oss.OSSClient.doesBucketExist(OSSClient.java:465)
          at com.aliyun.oss.demo.HelloOSS.main(HelloOSS.java:82)
  Caused by: java.lang.ClassNotFoundException: org.jdom.input.SAXBuilder
          at java.net.URLClassLoader$1.run(URLClassLoader.java:366)
          at java.net.URLClassLoader$1.run(URLClassLoader.java:355)
          at java.security.AccessController.doPrivileged(Native Method)
          at java.net.URLClassLoader.findClass(URLClassLoader.java:354)
          at java.lang.ClassLoader.loadClass(ClassLoader.java:425)
          at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)
          at java.lang.ClassLoader.loadClass(ClassLoader.java:358)
          ... 11 more
                      

  OSS Java SDK V1 は、以下のパッケージに依存しています：

  • aliyun-sdk-oss-2.2.1.jar

  • hamcrest-core-1.1.jar

  • jdom-1.1.jar

  • commons-codec-1.9.jar

  • httpclient-4.4.1.jar

  • commons-logging-1.2.jar

  • httpcore-4.4.1.jar

  • log4j-1.2.15.jar

  これらのうち、log4j-1.2.15.jar はオプションの依存関係です。このパッケージは、ロギング機能が必要な場合にのみ追加してください。その他のパッケージは必須です。

• 解決策

  OSS Java SDK V1 が依存するパッケージをプロジェクトに追加してください。次のいずれかの方法を使用できます。

  • Eclipse プロジェクト：「SDK のインストール」をご参照ください。

  • Ant プロジェクト：OSS Java SDK V1 が依存するパッケージをプロジェクトの lib ディレクトリに配置してください。

  • 直接コンパイル：-classpath または -cp コマンドを使用して、OSS Java SDK V1 が依存するパッケージのパスを指定するか、これらのパッケージをクラスパスに配置してください。

接続タイムアウト

• 原因

  OSS Java SDK V1 プログラムを実行すると、エンドポイントが正しくないか、ネットワーク接続の問題により、以下のようなエラーが発生することがあります。

  com.aliyun.oss.ClientException: SocketException
      at com.aliyun.oss.common.utils.ExceptionFactory.createNetworkException(ExceptionFactory.java:71)
      at com.aliyun.oss.common.comm.DefaultServiceClient.sendRequestCore(DefaultServiceClient.java:116)
      at com.aliyun.oss.common.comm.ServiceClient.sendRequestImpl(ServiceClient.java:121)
      at com.aliyun.oss.common.comm.ServiceClient.sendRequest(ServiceClient.java:67)
      at com.aliyun.oss.internal.OSSOperation.send(OSSOperation.java:92)
      at com.aliyun.oss.internal.OSSOperation.doOperation(OSSOperation.java:140)
      at com.aliyun.oss.internal.OSSOperation.doOperation(OSSOperation.java:111)
      at com.aliyun.oss.internal.OSSBucketOperation.getBucketInfo(OSSBucketOperation.java:1152)
      at com.aliyun.oss.OSSClient.getBucketInfo(OSSClient.java:1220)
      at com.aliyun.oss.OSSClient.getBucketInfo(OSSClient.java:1214)
      at com.aliyun.oss.demo.HelloOSS.main(HelloOSS.java:94)
  Caused by: org.apache.http.conn.HttpHostConnectException: Connect to oss-test.oss-cn-hangzhou-internal.aliyuncs.com:80 [oss-test.oss-cn-hangzhou-internal.aliyuncs.com/10.84.135.99] failed: Connection timed out: connect
      at org.apache.http.impl.conn.DefaultHttpClientConnectionOperator.connect(DefaultHttpClientConnectionOperator.java:151)
      at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.connect(PoolingHttpClientConnectionManager.java:353)
      at org.apache.http.impl.execchain.MainClientExec.establishRoute(MainClientExec.java:380)
      at org.apache.http.impl.execchain.MainClientExec.execute(MainClientExec.java:236)
      at org.apache.http.impl.execchain.ProtocolExec.execute(ProtocolExec.java:184)
      at org.apache.http.impl.execchain.RedirectExec.execute(RedirectExec.java:110)
      at org.apache.http.impl.client.InternalHttpClient.doExecute(InternalHttpClient.java:184)
      at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:82)
      at com.aliyun.oss.common.comm.DefaultServiceClient.sendRequestCore(DefaultServiceClient.java:113)
      ... 9 more
                      

• 解決策

  ossutil ツールを使用してエラーの原因を迅速に特定し、問題を解決できます。

SignatureDoesNotMatch エラー

• 原因 1：AccessKey ペア情報の不一致

  AccessKey ID と AccessKey シークレットが一致しません。AccessKey ID と AccessKey シークレットの取得方法については、「アクセスキーペアの作成」をご参照ください。

• 原因 2：署名付き URL の誤った使用方法

  以下は、署名付き URL の誤った使用例です。

  GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketName, object);
  request.setExpiration( new Date(new Date().getTime() + 3600 * 1000));
  request.addUserMetadata("author", "Alice");
  URL url = ossClient.generatePresignedUrl(request);
  
  Map<String, String> header = new HashMap<String, String>();
  header.put("author", "Alice");
  ossClient.putObject(url, new ByteArrayInputStream("Hello OSS".getBytes()), -1, header);

  Method パラメーターが指定されていない場合、デフォルトで GET メソッドが使用されます。しかし、上記の例は PutObject リクエストです。したがって、Method パラメーターを指定し、PUT に設定する必要があります。

  PutObject リクエストを送信する際、リクエストヘッダー内のカスタムメタデータには x-oss-meta- というプレフィックスを付ける必要があります。上記の例では、カスタムメタデータは x-oss-meta-author に変更する必要があります。

  解決策：

  Method パラメーターを指定し、ヘッダーのプレフィックスを修正してください。

  GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketName, object);
  request.setExpiration( new Date(new Date().getTime() + 3600 * 1000));
  request.addUserMetadata("author", "Alice");
  request.setMethod(HttpMethod.PUT);
  URL url = ossClient.generatePresignedUrl(request);
  
  Map<String, String> header = new HashMap<String, String>();
  header.put("x-oss-meta-author", "Alice");
  ossClient.putObject(url, new ByteArrayInputStream("Hello OSS".getBytes()), -1, header);

• 原因 3：HttpClient のバージョン互換性の問題

  • OSS SDK のバージョンが 3.7.0 より前で、プロジェクトに HttpClient 4.5.9 以降が導入されている。

  • アップロードされたファイル名に + 文字が含まれ、HttpClient 4.5.9 は + 文字を URL エンコードしません。これにより、クライアントとサーバーで計算された署名が一致しなくなります。

  

  解決策：

  • OSS SDK をバージョン 3.11.1 以降にアップグレードして、HttpClient 4.5.9 との互換性を確保してください。

  • 冗長な HttpClient の依存関係を削除してください。OSS SDK を導入すると、HttpClient の依存関係が自動的に導入されます。サードパーティのライブラリも HttpClient を導入している場合は、「パッケージの競合」の解決策をご参照ください。

• 原因 4：HttpClient の文字セット互換性の問題

  HttpClient 4.5.10 は、ヘッダー内で ISO-8859-1 標準外の文字をサポートしていません。そのため、4.5.10 より後のバージョンの HttpClient を使用するプロジェクトで、リクエストヘッダーの x-oss-meta- から始まるカスタムメタデータに中国語文字などの ISO-8859-1 標準外の文字が含まれていると、問題が発生します。

  解決策：

  • 「パッケージの競合」の解決策を参照して、競合する HttpClient バージョンを削除します。

  • リクエストヘッダーには、ISO-8859-1 標準に準拠した文字のみを渡してください。

「Failed to parse the response result」例外

• 原因

  クライアント側の特定の特殊なソフトウェアが HTTP リクエストを傍受しているか、パブリックネットワークのルートが HTTP リクエストをハイジャックしています。

  Java 9 以降で OSS Java SDK V1 を使用していて、pom.xml ファイルに JAXB 関連の依存関係を追加していない場合。

• 解決策

  HTTPS リクエストに切り替えてください。

  JAXB 関連の依存関係を追加してください。手順については、「SDK のインストール」をご参照ください。

org.apache.http.NoHttpResponseException: The target server failed to respond

• 原因

  OSS Java SDK V1 プログラムを実行すると、次のようなエラーが報告されることがあります。

  

  期限切れの接続を使用すると、上記のエラーが発生します。このエラーは、2.1.2 より前の Java SDK バージョンでのみ発生します。

• 解決策

  OSS Java SDK V1 をバージョン 2.1.2 以降にアップグレードしてください。

JVM 内に多数の org.apache.http.impl.conn.PoolingHttpClientConnectionManager インスタンスが存在する

• 原因

  ossClient が正しくクローズされていません。

• 解決策

  実行が終了した後に ossClient をクローズするか、シングルトンパターンを使用してください。

OSS Java SDK V1 の呼び出しが応答しない

• 原因

  OSS Java SDK V1 の呼び出しが応答しません。jstack -l pid コマンドを実行してスタックを確認すると、以下の位置で問題を特定できます。

  "main" prio=6 tid=0x000000000291e000 nid=0xc40 waiting on condition [0x0000000002dae000]
  java.lang.Thread.State: WAITING (parking)
      at sun.misc.Unsafe.park(Native Method)
      - parking to wait for  <0x00000007d85697f8> (a java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject)
      at java.util.concurrent.locks.LockSupport.park(LockSupport.java:186)
      at java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject.await(AbstractQueuedSynchronizer.java:2043)
      at org.apache.http.pool.PoolEntryFuture.await(PoolEntryFuture.java:138)
      at org.apache.http.pool.AbstractConnPool.getPoolEntryBlocking(AbstractConnPool.java:306)
      at org.apache.http.pool.AbstractConnPool.access$000(AbstractConnPool.java:64)
      at org.apache.http.pool.AbstractConnPool$2.getPoolEntry(AbstractConnPool.java:192)
      at org.apache.http.pool.AbstractConnPool$2.getPoolEntry(AbstractConnPool.java:185)
      at org.apache.http.pool.PoolEntryFuture.get(PoolEntryFuture.java:107)
      at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.leaseConnection(PoolingHttpClientConnectionManager.java:276)
      at org.apache.http.impl.conn.PoolingHttpClientConnectionManager$1.get(PoolingHttpClientConnectionManager.java:263)
      at org.apache.http.impl.execchain.MainClientExec.execute(MainClientExec.java:190)
      at org.apache.http.impl.execchain.ProtocolExec.execute(ProtocolExec.java:184)
      at org.apache.http.impl.execchain.RedirectExec.execute(RedirectExec.java:110)
      at org.apache.http.impl.client.InternalHttpClient.doExecute(InternalHttpClient.java:184)
      at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:82)
      at com.aliyun.oss.common.comm.DefaultServiceClient.sendRequestCore(DefaultServiceClient.java:113)
      at com.aliyun.oss.common.comm.ServiceClient.sendRequestImpl(ServiceClient.java:123)
      at com.aliyun.oss.common.comm.ServiceClient.sendRequest(ServiceClient.java:68)
      at com.aliyun.oss.internal.OSSOperation.send(OSSOperation.java:94)
      at com.aliyun.oss.internal.OSSOperation.doOperation(OSSOperation.java:146)
      at com.aliyun.oss.internal.OSSOperation.doOperation(OSSOperation.java:113)
      at com.aliyun.oss.internal.OSSObjectOperation.getObject(OSSObjectOperation.java:229)
      at com.aliyun.oss.OSSClient.getObject(OSSClient.java:629)
      at com.aliyun.oss.OSSClient.getObject(OSSClient.java:617)
      at samples.HelloOSS.main(HelloOSS.java:49)
                      

  接続プールの接続リークが原因です。使用後に ossObject が正しくクローズされなかった可能性があります。

• 解決策

  プログラムをチェックして、接続リークがないことを確認してください。以下の方法で接続を正しくクローズしてください。

  // ファイルを読み取ります。
  OSSObject ossObject = ossClient.getObject(bucketName, objectName);
  // OSS 操作
  // ossObject をクローズします。
  ossObject.close();                

  詳細なトラブルシューティング手順については、「応答しない OSS Java SDK V1 のトラブルシューティング」をご参照ください。

接続のクローズ

• 原因

  ossClient.getObject を使用する際に、以下のようなエラーが発生することがあります。

  Exception in thread "main" org.apache.http.ConnectionClosedException: Premature end of Content-Length delimited message body (expected: 11990526; received: 202880)
      at org.apache.http.impl.io.ContentLengthInputStream.read(ContentLengthInputStream.java:180)
      at org.apache.http.impl.io.ContentLengthInputStream.read(ContentLengthInputStream.java:200)
      at org.apache.http.impl.io.ContentLengthInputStream.close(ContentLengthInputStream.java:103)
      at org.apache.http.impl.execchain.ResponseEntityProxy.streamClosed(ResponseEntityProxy.java:128)
      at org.apache.http.conn.EofSensorInputStream.checkClose(EofSensorInputStream.java:228)
      at org.apache.http.conn.EofSensorInputStream.close(EofSensorInputStream.java:174)
      at java.io.FilterInputStream.close(FilterInputStream.java:181)
      at java.io.FilterInputStream.close(FilterInputStream.java:181)
      at com.aliyun.oss.event.ProgressInputStream.close(ProgressInputStream.java:147)
      at java.io.FilterInputStream.close(FilterInputStream.java:181)
      at samples.HelloOSS.main(HelloOSS.java:39)
                      

  このエラーは、2回のデータ読み取りの間隔が1分を超えたために発生します。OSS は、1 分以上アイドル状態の接続をクローズします。

• 解決策

  毎回データの一部のみを読み取り、処理時間が変動する場合は、接続のクローズを避けるために範囲指定ダウンロードを使用してください。範囲指定ダウンロードが完了すると、接続は自動的にクローズされます。「範囲指定ダウンロード (OSS Java SDK V1)」をご参照ください。

メモリリーク

• 原因

  OSS Java SDK V1 を呼び出すプログラムが、一定期間（ビジネスの量に応じて数時間から数日）実行された後にメモリリークを起こします。Eclipse Memory Analyzer (MAT) を使用してメモリ使用量を分析することを推奨します。詳細については、「MAT を使用したヒープダンプファイルの分析」をご参照ください。

  分析結果が下の図のようになる場合（PoolingHttpClientConnectionManager がメモリの 96% を占有）、原因はプログラム内で new OSSClient が複数回実行されたにもかかわらず、ossClient.shutdown が呼び出されなかったことです。

  

• 解決策

  new OSSClient 操作が完了した後、shutdown メソッドを呼び出してクローズしてください。new OSSClient と ossClient.shutdown がペアで使用されていることを確認してください。

ossClient.shutdown の呼び出し時に InterruptedException が報告される

• 原因

  2.3.0 より前のバージョンの OSS Java SDK V1 は、ossClient.shutdown を呼び出すと以下の例外を報告することがあります。

  java.lang.InterruptedException: sleep interrupted
          at java.lang.Thread.sleep(Native Method)
          at com.aliyun.oss.common.comm.IdleConnectionReaper.run(IdleConnectionReaper:76)      

  原因は、ossClient のバックエンドスレッド IdleConnectionReaper が定期的にアイドル接続をクローズするためです。IdleConnectionReaper が Sleep 中に ossClient.shutdown が呼び出されると、上記の例外が報告されます。

• 解決策

  次のコードを使用して例外を無視してください。

  try {
      ossClient.shutdown();
  } catch(Exception e) {
  }                  

「SDK.ServerUnreachable : Speicified endpoint or uri is not valid」例外

• 原因

  • クライアントから STS への同時リクエストが多すぎること。

  • サーバーへのネットワーク接続がタイムアウトすること。

  • 使用している STS SDK と SDK コアが最新バージョンではないこと。

• 解決策

  • OSS の同時実行数を減らしてください。クライアントが STS に送信する同時リクエストが多すぎる場合、クライアントの ECS インスタンスまたはローカルコンピュータが負荷を処理できない可能性があります。

  • ユーザーからサーバーへのネットワーク接続がタイムアウトします。パケットをキャプチャしてこれを確認できます。

  • STS SDK と SDK コアを最新バージョンにアップグレードしてください。

NoSuchKey

• 原因

  ソースファイルが存在しません。

• 解決策

  「404 エラー」をご参照ください。

SocketException

• 原因

  初期化フェーズでソケットが失敗し、リクエストが OSS に到達する前に失敗した可能性があります。

• 解決策

  以下の点を確認することを推奨します。

  • 問題発生時にネットワークのジッターが発生したかどうか。

  • ホストのソケット接続数が上限に達していないかどうか。

  • 問題発生時に接続数が SDK の maxconnection 設定を超えていないか確認してください。接続数が maxconnection 設定を超えると、ソケット例外も発生します。

  上記に問題がない場合は、tcpdump または Wireshark をデプロイしてパケットをキャプチャし、問題が再発した後にデータパケットを分析することを推奨します。

OSS PostObject のコールバックがトリガーされない

OSS PostObject のコールバックがトリガーされませんが、同じコールバックは PutObject によってトリガーされます。通常、JSON 形式が正しくないか、コールバックが失敗すると、対応するメッセージが返されます。この場合、Put と Post のコールバック動作を個別にテストする必要があります。

• 原因

  リクエストを送信する際、callback パラメーターが誤って file パラメーター内に配置されています。

• 解決策

  callback と file パラメーターの位置を調整してください。

  この時点で、テスト結果はビジネスサーバーがリクエストを正常にキャプチャしたことを示します。

接続プールがシャットダウンされた

Caused by: java.lang.IllegalStateException: Connection pool shut down
  at org.apache.http.util.Asserts.check(Asserts.java:34)
  at org.apache.http.pool.AbstractConnPool.lease(AbstractConnPool.java:184)
  at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.requestConnection(PoolingHttpClientConnectionManager.java:251)
  at org.apache.http.impl.execchain.MainClientExec.execute(MainClientExec.java:175)
  at org.apache.http.impl.execchain.ProtocolExec.execute(ProtocolExec.java:184)
  at org.apache.http.impl.execchain.RedirectExec.execute(RedirectExec.java:110)
  at org.apache.http.impl.client.InternalHttpClient.doExecute(InternalHttpClient.java:184)
  at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:82)
  at com.aliyun.oss.common.comm.DefaultServiceClient.sendRequestCore(DefaultServiceClient.java:124)
  at com.aliyun.oss.common.comm.ServiceClient.sendRequestImpl(ServiceClient.java:133)
  ... 8 more

• 原因

  ossClient.shutdown() メソッドを呼び出した後も、ossClient を通じてリクエストを送信し続けていることが原因です。

• 解決策

  呼び出しロジックを確認し、ossClient.shutdown() メソッドを呼び出した後は、ossClient を通じてリクエストを送信しないようにしてください。

Java SDK の generatePresignedUrl によって生成されたリクエストで「Request has expired」エラーが発生する

• 原因

  整数オーバーフローが原因で、2038年問題に関連するタイムスタンプの問題が発生すること。

  URL に設定された有効期限後にアップロードリクエストが開始されること。

• 解決策

  整数オーバーフローの場合は、Java SDK の有効期限を 2038 年を超えないように設定することを推奨します。

  URL に設定された有効期限後にアップロードリクエストが開始される場合は、リクエストを開始する時刻より後の有効期限になるように、合理的な有効期限を設定してください。

「Invalid Response」または「Implementation of JAXB-API has not been found on module path or classpath」エラー

• 原因

  Java 9 以降を使用しているにもかかわらず、JAXB の依存関係が追加されていないこと。

• 解決策

  JAXB の依存関係を追加する方法については、「SDK のインストール」をご参照ください。

OSS Java SDK V1 の OSSClient はスレッドセーフですか？

1. OSSClient はスレッドセーフであり、複数のスレッドが同じインスタンスにアクセスできます。ビジネスニーズに応じて、単一の OSSClient インスタンスを再利用するか、複数のインスタンスを作成することができます。

2. OSSClient インスタンスは内部で接続プールを維持します。OSSClient インスタンスが不要になった場合は、shutdown メソッドを呼び出してクローズし、OSSClient インスタンスを多数作成することによるリソースの枯渇を避ける必要があります。

「AccessDenied Hierarchical namespace is disabled」エラーが報告される

• 原因

  CreateDirectory、Rename、または DeleteDirectory API を呼び出す前に、階層型名前空間が有効にされていません。

• 解決策

  バケットを作成する際に階層型名前空間を有効にしてください。具体的な手順については、「バケットの作成」をご参照ください。

クライアントネットワークは正常なのに、HTTP アクセス中に「Connection reset」エラーが報告されます。どうすればよいですか？

一部の地域の通信事業者が OSS ドメイン名をハイジャックする可能性があります。エンドポイントを通じて HTTPS を設定してください。「クライアントの設定」をご参照ください。

Java 17 で「Cannot invoke "java.lang.reflect.Method.invoke(Object, Object[])" because "com.sun.xml.bind.v2.runtime.reflect.opt.Injector.defineClass" is null」

• 原因

  JAXB は Java 9 で非推奨となり、Java 11 で削除されました。

• 解決策

  以下の依存関係を追加してください。

      <dependency>
          <groupId>com.sun.xml.bind</groupId>
          <artifactId>jaxb-impl</artifactId>
          <version>2.3.1</version>
      </dependency>
      <dependency>
          <groupId>com.sun.xml.messaging.saaj</groupId>
          <artifactId>saaj-impl</artifactId>
          <version>1.5.1</version>
      </dependency>

Java SDK の内部ログ出力を設定するにはどうすればよいですか？

Java SDK は、ログ出力に Apache Commons Logging (JCL) フレームワークを使用します。JCL は複数のロギング実装フレームワークを使用できます。詳細については、「JCL-Configuration」をご参照ください。最も一般的なのは、JCL over log4j または JCL over SLF4j です。実装方法は次のとおりです。

• JCL over log4j：log4j の依存関係 (log4j 2.x には複数の実装フレームワークがあり、デフォルトは log4j-api+log4j-core) を導入し、log4j の設定方法に従って設定する必要があります。具体的なプロセスについては、「APACHE LOG4J-API Separation」をご参照ください。

• JCL over slf4j：jcl-over-slf4j と slf4j の依存関係 (slf4j も slf4j-api+logback-classic など複数の実装フレームワークから選択可能) を導入し、slf4j の設定方法に従って設定する必要があります。具体的なプロセスについては、「SLF4J-Bridging legacy APIs」をご参照ください。

Apache Log4j は、OFF、FATAL、ERROR、WARN、INFO、DEBUG、TRACE、ALL など、さまざまなログレベルを定義しています。

log4j のプロパティを設定することで、SDK のログを有効または無効にできます。