OSSClient は、バケットやオブジェクトなどの OSS リソースを管理するための OSS Java クライアントとして機能します。 Java SDK で OSS リクエストを開始するには、まず OSSClient インスタンスを開始してからClientConfiguration のデフォルト設定項目を変更する必要があります。

OSSClientインスタンスの作成

OSSClient インスタンスを作成するには、エンドポイントを指定する必要があります。 エンドポイントの詳細については、「リージョンおよびエンドポイント」および「カスタムドメイン名のバインド方法」をご参照ください。

  • OSS ドメインを使用して OSSClient インスタンスを作成

    次のコードを実行して、OSS によって割り当てられたドメインを使用して OSSClient インスタンスを作成します

    // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create an OSSClient instance.
    OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
    
    // Close your OSSClient instance.
    ossClient.shutdown();
    					

    プロジェクトには1つ以上の OSS クライアントを使用できます。 つまり、複数の OS クライアントを同時に使用することができます。

  • カスタムドメイン (CNAME) を使用して OSSClient インスタンスを作成

    次のコードを実行して、CNAME で OSSClient インスタンスを作成します。

    String endpoint = "<yourEndpoint>";
    // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create a ClientConfiguration instance. Modify parameters as required.
    ClientConfiguration conf = new ClientConfiguration();
    // Enable CNAME. CNAME indicates a custom domain bound to a bucket.
    conf.setSupportCname(true);
    
    // Create an OSSClient instance.
    OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
    
    // Close your OSSClient instance.
    ossClient.shutdown();
    					
    CNAME が使用されている場合、ossClient.listBuckets メソッドは使用できません。
  • Apsara Stack の OSSClient インスタンスを作成

    次のコードを実行して、Apsara Stack の OSSClient インスタンスを作成します。

    // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create a ClientConfiguration instance. Modify parameters as required.
    ClientConfiguration conf = new ClientConfiguration();
    // Disable CNAME.
    conf.setSupportCname(false);
    
    // Create an OSSClient instance.
    OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
    
    // Close your OSSClient instance.
    ossClient.shutdown();
    					
  • IP アドレスを使用して OSSClient インスタンスを作成

    次のコードを実行して、IP アドレスを指定して OSSClient インスタンスを作成します。

    // In some special cases, use the IP address as an endpoint. Specify the actual IP address based on your requirements.
    String endpoint = "http://10.10.10.10";
    // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create ClientConfiguration.
    ClientConfiguration conf = new ClientConfiguration();
    // Enable OSS access with the level-2 domain. Access with the level-2 domain is disabled by default. You need to configure this function for OSS Java SDK versions 2.1.2 or earlier because OSS Java SDK versions later than 2.1.2 automatically detect IP addresses.
    conf.setSLDEnabled(true);
    
    // Create an OSSClient instance.
    OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
    
    // Close your OSSClient instance.
    ossClient.shutdown();
    					
  • STS を使用して OSSClient インスタンスを作成

    以下のコードを実行して、STS (Security Token Service) を使用して OSSClient インスタンスを作成します。

    // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String securityToken = "<yourSecurityToken>";
    
    // Create an OSSClient instance.
    OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, securityToken);
    
    // Close your OSSClient instance.
    ossClient.shutdown();
    					

詳しくは、「RAM および STS の概要」および「許可されたアクセス」をご参照ください。

OSSClient インスタンスの設定

ClientConfiguration は OSSClient の設定クラスです。 ClientConfiguration は、ユーザーエージェント、ホストプロキシ、接続タイムアウト、最大接続数などのパラメーターを設定するために使用されます。 以下のパラメーターを設定できます。

パラメータ 説明 設定方法
MaxConnections 有効にできる HTTP 接続の最大数を指定します。 デフォルト値は 1024 です。 ClientConfiguration.setMaxConnections
SocketTimeout ソケット層でのデータ転送のタイムアウト時間をミリ秒単位で指定します。 デフォルト値は 50,000 です。 ClientConfiguration.setSocketTimeout
ConnectionTimeout 接続が確立されるときのタイムアウト時間をミリ秒単位で指定します。 <p data-spm-anchor-id="a2762.11472859.0.i61.7eca203bijNJDs">デフォルト値は 50,000 秒です。 ClientConfiguration.setConnectionTimeout
ConnectionRequestTimeout 接続プールから接続を取得するためのタイムアウト時間をミリ秒単位で指定します。 デフォルトではタイムアウトは設定されていません。 デフォルトではタイムアウトは設定されていません。 ClientConfiguration.setConnectionRequestTimeout
IdleConnectionTime アイドル接続タイムアウト時間を指定します。 ミリ秒単位のアイドル接続時間が指定された値を超えると、接続は閉じられます。 デフォルト値は 60,000 です。 ClientConfiguration.setIdleConnectionTime
MaxErrorRetry リクエストエラーが発生した場合の最大再試行回数を指定します。 デフォルト値は 3 です。 ClientConfiguration.setMaxErrorRetry
SupportCname CNAME をエンドポイントとして使用できるかどうかを指定します。 デフォルトで CNAME をエンドポイントとして使用できます。 ClientConfiguration.setSupportCname
SLDEnabled レベル 2 ドメインとのアクセスを有効にするかどうかを指定します。 レベル 2 ドメインでのアクセスは、デフォルトで無効になっています。 ClientConfiguration.setSLDEnabled
Protocol OSS への接続に使用されるプロトコル(HTTP または HTTPS)を指定します。 デフォルト値は HTTP です。 ClientConfiguration.setProtocol
UserAgent HTTP ヘッダー内のユーザエージェントを指定します。 デフォルト値は “aliyun-sdk-java” です。 ClientConfiguration.setUserAgent
ProxyHost プロキシホストにアクセスするための IP アドレスを指定します。 ClientConfiguration.setProxyHost
ProxyPort プロキシホストのポートを指定します。 ClientConfiguration.setProxyPort
ProxyUsername プロキシホストによって確認されたユーザ名を指定します。 ClientConfiguration.setProxyUsername
ProxyPassword プロキシホストによって確認されたパスワードを指定します。 ClientConfiguration.setProxyPassword

次のコードを実行して、ClientConfiguration を使用して OSSClient インスタンスのパラメーターを構成します。

// This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// Create ClientConfiguration. ClientConfiguration is a configuration class of OSSClient. You can use ClientConfiguration to configure parameters such as user agents, host proxies, connection timeout, and the maximum number of connections.
ClientConfiguration conf = new ClientConfiguration();

// Configure the maximum HTTP connections allowed by an OSSClient instance. The default value is 1024.
conf.setMaxConnections(200);
// Configure the timeout time in milliseconds for data transmission at SSL. The default value is 50,000.
conf.setSocketTimeout(10000);
conf.setSocketTimeout(10000);
// Configure the timeout time in milliseconds when connections are established. The default value is 50,000.
conf.setConnectionTimeout(10000);
// Configure the timeout time in milliseconds for retrieving connections from the connection pool. This function is disabled by default.
conf.setConnectionRequestTimeout(1000);
// Configure idle connection timeout. If the idle connection time in milliseconds exceeds the specified value, the connection is closed. The default value is 60,000.
conf.setIdleConnectionTime(10000);
// Configure the maximum number of retry attempts in the case of a request error. The default value is 3.
conf.setMaxErrorRetry(5);
// Check whether CNAME can be used as an endpoint. You can use CNAME as an endpoint by default.
conf.setSupportCname(true);
// Check whether access with the level-2 domain is enabled. Access with the level-2 domain is disabled by default.
conf.setSLDEnabled(true);
// Configure the protocol (HTTP or HTTPS) used to connect to OSS. HTTP is used by default.
conf.setProtocol(Protocol.HTTP);
// Configure the user agent (the user agent in the HTTP header). The default value is "aliyun-sdk-java."
conf.setUserAgent("aliyun-sdk-java");
// Configure the port for the proxy host.
conf.setProxyHost("<yourProxyHost>");
// Configure the username verified by the proxy host.
conf.setProxyUsername("<yourProxyUserName>");
// Configure the password verified by the proxy host.
conf.setProxyPassword("<yourProxyPassword>");

// Create an OSSClient instance.
OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);

// Close your OSSClient instance.
ossClient.shutdown();