OSSClientは、Object Storage Service (OSS) のJavaクライアントです。 バケットやオブジェクトなどのOSSリソースの管理に使用されます。 OSS SDK for Javaを使用してリクエストを開始するには、OSSClientインスタンスを初期化し、ClientConfigurationのデフォルト設定項目を変更する必要があります。
前提条件
アクセス資格情報が設定されます。 詳細については、「アクセス資格情報の設定」をご参照ください。
OSSClientインスタンスの作成
OSSClientはスレッドセーフで、複数のスレッドを使用して同じインスタンスにアクセスできます。 同じOSSClientインスタンスを再利用するか、ビジネス要件に基づいて複数のOSSClientインスタンスを作成できます。
OSSClientインスタンスには接続プールがあります。 OSSClientインスタンスを使用しなくなった場合は、shutdownメソッドを呼び出してOSSClientインスタンスをシャットダウンします。 これにより、OSSClientインスタンスの数が多すぎることによるリソースの枯渇を防ぎます。
V1署名アルゴリズムの使用
OSSエンドポイントを使用したOSSClientインスタンスの作成
次のサンプルコードは、OSSエンドポイントを使用してOSSClientインスタンスを作成する方法の例を示しています。 さまざまなリージョンのOSSエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。
// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。
String endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// OSSClientインスタンスを作成します。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
カスタムドメイン名を使用したOSSClientインスタンスの作成
次のサンプルコードは、カスタムドメイン名を使用してOSSClientインスタンスを作成する方法の例を示しています。 詳細については、「カスタムドメイン名をバケットのデフォルトドメイン名にマップする」をご参照ください。
カスタムドメイン名を使用する場合、ossClient.listBucketsメソッドは使用できません。
// カスタムドメイン名を指定します。
String endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// ClientBuilderConfigurationを作成し、ビジネス要件に基づいてパラメーターのデフォルト値を変更します。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// CNAMEを使用するかどうかを指定します。 CNAMEは、カスタムドメイン名をバケットにマップするために使用されます。
conf.setSupportCname(true);
// OSSClientインスタンスを作成します。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
STSから取得したアクセス資格情報を使用したOSSClientインスタンスの作成
次のサンプルコードは、Security Token Service (STS) から取得したアクセス資格情報を使用してOSSClientインスタンスを作成する方法の例を示しています。
STSの設定方法の詳細については、「STSが提供する一時的な資格情報を使用してOSSにアクセスする」をご参照ください。
AssumeRole操作を呼び出すか、さまざまなプログラミング言語のSTS SDKを使用して、一時的なアクセス資格情報を取得できます。 詳細については、「STS SDKの概要」をご参照ください。
一時的なアクセス資格情報は、一時的なAccessKeyペアとセキュリティトークンで構成されます。 一時的なAccessKeyペアは、AccessKey IDとAccessKeyシークレットで構成されます。 一時的なアクセス資格情報の有効期間は秒単位です。 一時的なアクセス資格情報の最小有効期間は900秒です。 一時的なアクセス資格情報の最大有効期間は、現在のロールに指定されている最大セッション期間です。 詳細については、「RAMロールの最大セッション期間の指定」をご参照ください。
完全なサンプルコードについては、「許可されたアクセス」をご参照ください。
// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。
String endpoint = "yourEndpoint";
// 環境変数から一時的なアクセス資格情報を取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// OSSClientインスタンスを作成します。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
STSAssumeRoleを使用したOSSClientインスタンスの作成
次のサンプルコードは、STSAssumeRoleを使用してOSSClientインスタンスを作成する方法の例を示しています。
// STSAssumeRoleにアクセスを許可するリージョンを指定します。 この例では、中国 (杭州) リージョンが使用されています。 実際のリージョンを指定します。
文字列region = "cn-hangzhou";
// 環境変数からRAMユーザーのAccessKey IDとAccessKey secretを取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
文字列accessKeyId = System.getenv("ALIYUN_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("ALIYUN_ACCESS_KEY_SECRET");
// 環境変数からRAMロールのRamRoleArnを取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
文字列roleArn = System.getenv("ALIYUN_STS_ROLE_ARN");
// STSAssumeRoleSessionCredentialsProviderインスタンスを作成します。
STSAssumeRoleSessionCredentialsProvider credentialsProvider = CredentialsProviderFactory.newSTSAssumeRoleSessionCredentialsProvider (
region、accessKeyId、accessKeySecret、roleArn);
// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。
String endpoint = "yourEndpoint";
// ClientBuilderConfigurationを作成します。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// OSSClientインスタンスを作成します。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
EcsRamRoleを使用したOSSClientインスタンスの作成
インスタンスにアタッチされたRAMロールを使用して、ECS (Elastic Compute Service) インスタンスからOSSにアクセスできます。 RAMロールをECSインスタンスにアタッチして、STSから取得した一時的なアクセス資格情報を使用してインスタンスからOSSにアクセスできます。 STSの一時的なアクセス資格情報は自動的に生成および更新されます。 アプリケーションは、インスタンスメタデータURLを使用してSTSの一時的なアクセス資格情報を取得できます。
次のサンプルコードは、EcsRamRoleを使用してOSSClientインスタンスを作成する方法の例を示しています。
// この例では、中国 (杭州) リージョンのエンドポイントが使用されます。 実際のエンドポイントを指定します。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// ecs-ram-roleを使用して一時的なアクセス資格情報を取得します。
InstanceProfileCredentialsProvider credentialsProvider=credentialsProvider. newInstanceProfileCredentialsProvider("ecs-ram-role");
// OSSClientインスタンスを作成します。
OSS ossClient = new OSSClientBuilder().build(endpoint、credentialsProvider、new ClientBuilderConfiguration());
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
Apsara StackまたはプライベートリージョンでのOSSClientインスタンスの作成
次のサンプルコードは、Apsara StackまたはプライベートリージョンでOSSClientインスタンスを作成する方法の例を示しています。
// バケットが配置されているリージョンのエンドポイントを指定します。
String endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// ClientBuilderConfigurationを作成し、ビジネス要件に基づいてパラメーターのデフォルト値を変更します。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// CNAMEを無効にします。
conf.setSupportCname(false);
// OSSClientインスタンスを作成します。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
IPアドレスを使用したOSSClientインスタンスの作成
次のサンプルコードは、IPアドレスを使用してOSSClientインスタンスを作成する方法の例を示しています。
// プライベートリージョンを含むシナリオなど、特定のシナリオでは、IPアドレスがエンドポイントとして使用されます。 これらのシナリオでは、実際のIPアドレスを指定する必要があります。
String endpoint = "https:// 10.10.10.10";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// ClientBuilderConfigurationを作成します。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// 第2レベルドメインからのアクセスを有効にします。 デフォルトでは、第2レベルドメインからのアクセスは無効になっています。 OSS SDK for Java 2.1.2以降は、IPアドレスを自動的に検出します。 バージョンが2.1.2より前のOSS SDK for Javaを使用する場合、このパラメーターを指定する必要があります。
conf.setSLDEnabled(true);
// OSSClientインスタンスを作成します。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
V4署名アルゴリズムの使用 (推奨)
V4署名アルゴリズムを使用する場合は、初期化の前にエンドポイントのリージョンをOSSClientインスタンスに追加し、署名バージョンをSignVersion.V4に設定する必要があります。 V4署名アルゴリズムは、V1署名アルゴリズムよりも安全である。 OSS SDK for Java 3.17.4以降はV4署名をサポートしています。
次のサンプルコードは、V4署名アルゴリズムを使用して署名されたOSSエンドポイントを使用してOSSClientインスタンスを作成する方法の例を示しています。 STSから取得したカスタムドメイン名またはアクセス資格情報を使用してOSSClientインスタンスを作成するには、次のサンプルコードを参照して変数を変更します。
// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// エンドポイントのリージョンを指定します。 例:cn-hangzhou。
文字列region = "cn-hangzhou";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// OSSClientインスタンスを作成します。
ClientBuilderConfiguration clientBuilderConfiguration=新しいClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
. endpoint(endpoint)
. credentialsProvider(credentialsProvider)
. clientConfiguration(clientBuilderConfiguration)
. region(region)
.build()
// Shut down the OSSClient instance.
ossClient.shutdown();
OSSClient インスタンスの設定
ClientConfigurationは、OSSClientインスタンスの構成クラスです。 ClientConfigurationを使用して、プロキシ、接続タイムアウト期間、最大接続数などのパラメーターを設定できます。 次の表に、OSSClientインスタンスを設定するときに設定できるパラメーターを示します。
パラメーター | 説明 | メソッド |
MaxConnections | 許可されるHTTP接続の最大数。 デフォルト値: 1024。 | ClientConfiguration.setMaxConnections |
SocketTimeout | ソケット層でのデータ送信のタイムアウト期間。 単位:ミリ秒。 デフォルト値: 50000 | ClientConfiguration.setSocketTimeout |
ConnectionTimeout | 接続を確立するためのタイムアウト期間。 単位:ミリ秒。 デフォルト値: 50000 | ClientConfiguration.setConnectionTimeout |
ConnectionRequestTimeout | 接続プールから接続を取得するためのタイムアウト時間。 単位:ミリ秒。 デフォルトでは、タイムアウト期間は無制限です。 | ClientConfiguration.setConnectionRequestTimeout |
IdleConnectionTime | アイドル接続のタイムアウト期間。 タイムアウト期間が終了すると、接続は閉じられます。 単位:ミリ秒。 デフォルト値: 60000 | ClientConfiguration.setIdleConnectionTime |
MaxErrorRetry | リクエストエラー発生時の最大リトライ回数。 デフォルト値: 3。 | ClientConfiguration.setMaxErrorRetry |
SupportCname | CNAME をエンドポイントとして使用できるかどうかを指定します。 デフォルトでは、CNAMEをエンドポイントとして使用できます。 | ClientConfiguration.setSupportCname |
SLDEnabled | 第2レベルドメインからのアクセスを有効にするかどうかを指定します。 デフォルトでは、第2レベルドメインからのアクセスは無効になっています。 | ClientConfiguration.setSLDEnabled |
プロトコル | OSSへの接続に使用されるプロトコル。 デフォルト値: HTTP。 有効な値: HTTPおよびHTTPS。 | ClientConfiguration.setProtocol |
UserAgent | ユーザーエージェント (HTTPヘッダーのuser-agentフィールド) 。 デフォルト値: | ClientConfiguration.setUserAgent |
ProxyHost | プロキシサーバーへのアクセスに使用されるホストのIPアドレス。 | ClientConfiguration.setProxyHost |
ProxyPort | プロキシサーバーへの接続に使用されるポート。 | ClientConfiguration.setProxyPort |
ProxyUsername | プロキシサーバーへのログオンに使用されるユーザー名。 | ClientConfiguration.setProxyUsername |
ProxyPassword | プロキシサーバーへのログインに使用されるパスワード。 | ClientConfiguration.setProxyPassword |
RedirectEnable | HTTPリダイレクトを有効にするかどうかを指定します。 説明 OSS SDK for Java 3.10.1以降のHTTPリダイレクトを有効にするかどうかを設定できます。 デフォルトでは、OSS SDK for Java 3.10.1以降でHTTPリダイレクトが有効になっています。 | ClientConfiguration.setRedirectEnable |
VerifySSLEnable | SSLベースの認証を有効にするかどうかを指定します。 説明 OSS SDK for Java 3.10.1以降のSSLベースの認証を有効にするかどうかを指定できます。 OSS SDK for Java 3.10.1以降では、デフォルトでSSLベースの認証が有効になっています。 | ClientConfiguration.setVerifySSLEnable |
次のサンプルコードは、ClientConfigurationを使用してOSSClientインスタンスのパラメーターを設定する方法の例を示しています。
// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。
String endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// ClientBuilderConfigurationを作成します。
// ClientBuilderConfigurationは、OSSClientインスタンスの構成クラスです。 ClientBuilderConfigurationを使用して、プロキシ、接続タイムアウト期間、最大接続数などのパラメーターを設定できます。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// OSSClientインスタンスが許可するHTTP接続の最大数を指定します。 デフォルト値: 1024。
conf.setMaxConnections(200);
// ソケット層でのデータ送信のタイムアウト期間を指定します。 単位:ミリ秒。 デフォルト値: 50000
conf.setSocketTimeout(10000);
// 接続を確立するためのタイムアウト時間を指定します。 単位:ミリ秒。 デフォルト値: 50000
conf.setConnectionTimeout(10000);
// 接続プールから接続を取得するためのタイムアウト時間を指定します。 単位:ミリ秒。 デフォルトでは、タイムアウト期間は無制限です。
conf.setConnectionRequestTimeout(1000);
// アイドル接続のタイムアウト期間を指定します。 タイムアウト期間が終了すると、接続は閉じられます。 単位:ミリ秒。 デフォルト値: 60000
conf.setIdleConnectionTime(10000);
// リクエストエラー発生時の最大リトライ回数を指定します。 デフォルト値: 3。
conf.setMaxErrorRetry (5);
// CNAMEをエンドポイントとして使用できるかどうかを指定します。 デフォルトでは、CNAMEをエンドポイントとして使用できます。
conf.setSupportCname(true);
// 第2レベルドメインからのアクセスを有効にするかどうかを指定します。 デフォルトでは、第2レベルドメインからのアクセスは無効になっています。
conf.setSLDEnabled(true);
// OSSへの接続に使用するプロトコルを指定します。 有効な値: HTTPおよびHTTPS。 デフォルト値: HTTP。
conf.setProtocol(Protocol.HTTP);
// HTTPヘッダーにUser-Agentを指定します。 デフォルト値: aliyun-sdk-java
conf.setUserAgent("aliyun-sdk-java");
// プロキシサーバーのIPアドレスを指定します。 <yourProxyHost> をプロキシサーバーのIPアドレスに置き換えます。 例: 196。 xxx.xxx.
conf.setProxyHost("<yourProxyHost>");
// プロキシサーバーによって検証されたユーザー名を指定します。 <yourProxyUserName> をプロキシサーバーのユーザー名に置き換えます。 例: root。
conf.setProxyUsername("<yourProxyUserName>");
// プロキシサーバーによって検証されたパスワードを指定します。 <yourProxyPassword> をユーザーのパスワードに置き換えます。
conf.setProxyPassword("<yourProxyPassword>");
// HTTPリダイレクトを有効にするかどうかを指定します。 デフォルト値:true
conf.setRedirectEnable(true);
// SSLベースの認証を有効にするかどうかを指定します。 デフォルト値:true
conf.setVerifySSLEnable(true);
// OSSClientインスタンスを作成します。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
再試行ポリシー
エラーが発生すると、OSSはリクエストタイプごとに異なる再試行ポリシーを使用します。
リクエストがPOSTリクエストの場合、OSSはデフォルトでリクエストを再試行しません。
非POSTリクエストが次のいずれかのシナリオに一致する場合、OSSはデフォルトの再試行ポリシーに基づいて最大3回までリクエストを再試行します。
ClientException例外が報告されると、ConnectionTimeout、SocketTimeout、ConnectionRefused、UnknownHost、またはSocketExceptionのいずれかのエラーコードが返されます。
OSSException例外が報告されると、InvalidResponse以外のエラーコードが返されます。
返されたHTTPステータスコードが500、502、または503の場合。
既定の再試行ポリシーがビジネス要件を満たせない場合は、カスタム再試行ポリシーを作成し、ClientConfigurationクラスを使用して再試行の最大数を設定できます。 ほとんどの場合、カスタム再試行ポリシーを作成しないことをお勧めします。 次のサンプルコードは、カスタム再試行ポリシーを作成する方法の例を示しています。
// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。
String endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// ClientBuilderConfigurationを作成します。
// ClientBuilderConfigurationは、OSSClientインスタンスの構成クラスです。 ClientBuilderConfigurationを使用して、再試行の最大数、カスタム再試行ポリシー、および接続タイムアウト期間を指定できます。
ClientBuilderConfiguration conf= new ClientBuilderConfiguration();
// リクエストエラー発生時の最大リトライ回数を指定します。 デフォルト値: 3。
conf.setMaxErrorRetry (5);
// カスタム再試行ポリシーを指定します。 ほとんどの場合、カスタム再試行ポリシーを指定しないことをお勧めします。
// たとえば、TestRetryStrategyクラスは、指定した再試行ポリシーです。 この場合、TestRetryStrategyクラスはRetryStrategyを継承する必要があります。
conf.setRetryStrategy (新しいTestRetryStrategy());
// OSSClientインスタンスを作成します。
OSS ossClient=new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// OSSClientインスタンスをシャットダウンします。
ossClient.shutdown();
次のステップ
OSSClientインスタンスを初期化した後、インスタンスを使用してリクエストを開始できます。 詳細については、「OSS SDK For Javaの使用を開始する」をご参照ください。