Use SDK V2.0 to initialize a client and make OpenAPI requests (Java SDK) - Alibaba Cloud SDK

OpenAPI işlemlerini çağırmak için projenize bir Alibaba Cloud SDK'sı entegre edin. Entegrasyon üç adımdan oluşur: SDK'yı içe aktarma, erişim kimlik bilgilerini ayarlama ve API'yi çağırma.

Ön Koşullar

JDK 1.8 veya sonraki bir sürüm.

SDK'yı İçe Aktarma

SDK Center adresine gidin ve kullanmak istediğiniz ürünü seçin (örneğin, Short Message Service (SMS)).
Install sayfasında, All Languages değerini Java olarak belirleyin. Ardından, Quick Start sekmesinde Short Message Service (SMS) SDK kurulum yöntemini bulun.

Erişim Kimlik Bilgilerini Ayarlama

Bir OpenAPI'yi çağırmak için AccessKey ve Security Token Service (STS) token gibi erişim kimlik bilgileri gerekir. Kimlik bilgilerinin sızmasını önlemek için bunları ortam değişkeni olarak saklayın. Güvenlik en iyi uygulamaları hakkında daha fazla bilgi için Erişim kimlik bilgilerini güvenli kullanma konusuna bakın. Aşağıdaki örnekte ALIBABA_CLOUD_ACCESS_KEY_ID ve ALIBABA_CLOUD_ACCESS_KEY_SECRET ortam değişkenleri kullanılmaktadır:

Linux ve macOS'ta yapılandırma yöntemi

Aşağıdaki örneklerde değişken adı olarak ALIBABA_CLOUD_ACCESS_KEY_ID ve ALIBABA_CLOUD_ACCESS_KEY_SECRET kullanılmıştır. Gerekirse bu adları kendi tercih ettiğiniz isimlerle değiştirin (örneğin, OSS_ACCESS_KEY_ID ve OSS_ACCESS_KEY_SECRET).

Ortam değişkenlerini ayarlamak için aşağıdaki export komutlarını çalıştırın:

Önemli

export ile ayarlanan değişkenler geçicidir ve yalnızca mevcut oturum için geçerlidir. Kalıcılık sağlamak üzere export komutunu kabuk başlangıç dosyanıza (örneğin, ~/.bashrc veya ~/.zshrc) ekleyin.

AccessKey ID değerini ayarlayın:

# Replace yourAccessKeyID with your AccessKey ID.
export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID

AccessKey gizli anahtarını ayarlayın:

# Replace yourAccessKeySecret with your AccessKey secret.
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret

Yapılandırmayı doğrulayın.

echo $ALIBABA_CLOUD_ACCESS_KEY_ID komutunu çalıştırın. Doğru değer döndürülüyorsa yapılandırma başarılıdır.

Windows'ta yapılandırma yöntemi

Grafiksel kullanıcı arabirimini (GUI) kullanma

Prosedür

Aşağıdaki adımlar, Windows 10'da GUI kullanarak ortam değişkenlerinin nasıl ayarlanacağını açıklar.

Masaüstünüzde This PC öğesine sağ tıklayın ve Properties > Advanced system settings > Environment Variables yolunu izleyin. System variables veya User variables bölümünün altındaki New seçeneğine tıklayın ve yapılandırmayı tamamlayın.

Değişken	Örnek değer
AccessKey ID	Değişken adı: ALIBABA_CLOUD_ACCESS_KEY_ID Değişken değeri: yourAccessKeyID
AccessKey gizli anahtarı	Değişken adı: ALIBABA_CLOUD_ACCESS_KEY_SECRET Değişken değeri: yourAccessKeySecret

Yapılandırmayı test edin

Start menüsüne tıklayın (veya Win+R klavye kısayolunu kullanın), Run seçeneğine tıklayın, cmd yazın ve ardından OK düğmesine tıklayarak (veya Enter tuşuna basarak) komut istemini açın. echo %ALIBABA_CLOUD_ACCESS_KEY_ID% ve echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET% komutlarını çalıştırın. Komutlar doğru AccessKey değerini döndürüyorsa yapılandırma başarılıdır.

Komut istemini (CMD) kullanma

Prosedür

Komut istemini yönetici olarak açın ve sisteme yeni ortam değişkenleri eklemek için aşağıdaki komutları çalıştırın.
```
setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M
```
/M parametresi bir sistem ortam değişkenini belirtir. Kullanıcı ortam değişkeni ayarlarken bu parametreyi atlayabilirsiniz.
Yapılandırmayı test edin

Start menüsüne tıklayın (veya Win+R klavye kısayolunu kullanın), Run seçeneğine tıklayın, cmd yazın ve ardından OK düğmesine tıklayarak (veya Enter tuşuna basarak) komut istemini açın. echo %ALIBABA_CLOUD_ACCESS_KEY_ID% ve echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET% komutlarını çalıştırın. Komutlar doğru AccessKey değerini döndürüyorsa yapılandırma başarılıdır.

Windows PowerShell'i kullanma

PowerShell'de tüm yeni oturumlarda geçerli olacak yeni ortam değişkenleri ayarlayabilirsiniz:

[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::User)

Tüm kullanıcılar için ortam değişkenleri ayarlamak üzere yönetici izinlerine sahip olmanız gerekir:

[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)

Yalnızca mevcut oturum için geçerli olacak geçici ortam değişkenleri ayarlayabilirsiniz:

$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "yourAccessKeyID"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "yourAccessKeySecret"

PowerShell'de Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID ve Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET komutlarını çalıştırın. Komutlar doğru AccessKey değerini döndürüyorsa yapılandırma başarılıdır.

SDK'yı Kullanma

Aşağıdaki örnekte, Short Message Service (SMS) hizmetinin SendMessageToGlobe API'si çağrılmaktadır. SendMessageToGlobe API referansı: SendMessageToGlobe.

1. İstek istemcisini başlatma

Tüm OpenAPI çağrıları bir istek istemcisinden (Client) kaynaklanır. Bu örnekte istemci bir AccessKey ile başlatılmaktadır. Diğer başlatma yöntemleri için Erişim kimlik bilgilerini yönetme konusuna bakın.

Önemli

Client örnekleri iş parçacığı açısından güvenlidir ve iş parçacıkları arasında paylaşılabilir.
Client nesnelerini new ile tekrar tekrar oluşturmayın. Her kimlik bilgisi ve uç nokta kümesi için tek bir istemciyi yeniden kullanmak üzere singleton tasarım desenini uygulayın.

public static com.aliyun.dysmsapi20180501.Client createClient() throws Exception {
    com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
            // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID is set.
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_SECRET is set.
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
    // See https://api.alibabacloud.com/product/Dysmsapi.
    config.endpoint = "dysmsapi.aliyuncs.com";
    return new com.aliyun.dysmsapi20180501.Client(config);
}

2. İstek nesnesi oluşturma

Parametreleri, <OpenAPIName>Request biçiminde adlandırılan SDK istek nesnesi aracılığıyla iletin (örneğin, SendSms için SendSmsRequest). İstek parametreleriyle ilgili ayrıntılar için: SendMessageToGlobe.

Not

Bir API'nin istek parametresi yoksa istek nesnesini atlayın (örneğin, DescribeCdnSubList).

com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest sendMessageToGlobeRequest = new com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest()
                .setTo("8521245567****")
                .setMessage("Hello");

3. İstek gönderme

API'yi, <apiName>WithOptions biçimindeki bir yöntemi kullanarak çağırın; burada <apiName> API adının camelCase biçimidir. Bu yöntem, istek nesnesini ve zaman aşımı, proxy ve diğer ayarları kontrol eden bir çalışma zamanı parametresini alır. Çalışma zamanı seçenekleriyle ilgili ayrıntılar için Gelişmiş yapılandırma konusuna bakın.

Not

Bir API'nin istek parametresi yoksa yalnızca çalışma zamanı parametresini iletin (örneğin, DescribeCdnSubList).

Yanıt nesneleri <OpenAPIName>Response adlandırma kuralını takip eder (örneğin, SendSmsResponse).

com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
Client client = createClient();
// call  api
client.sendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);

4. Özel durumları işleme

Java SDK'sında iki tür özel durum bulunur: TeaUnretryableException ve TeaException.

TeaUnretryableException: Genellikle ağ sorunlarından kaynaklanan ve tüm yeniden denemeler tükendiğinde tetiklenir.
TeaException: İş mantığı hataları için tetiklenir.

Özel durum işleme kalıplarıyla ilgili ayrıntılar için Özel durum işleme konusuna bakın.

Önemli

Sistem kararlılığını korumak için özel durumları her zaman uygun şekilde işleyin (yayınlayın, günlüğe kaydedin veya kurtarma işlemi uygulayın).

Tam kod örneğini görüntüle

SendMessageToGlobe API örnek çağrısı

import com.aliyun.dysmsapi20180501.Client;
import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest;
import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeResponse;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;

public class Sample {
    public static Client createClient() throws Exception {
        Config config = new Config()
                // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID is set.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_SECRET is set.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // See https://api.alibabacloud.com/product/Dysmsapi.
        config.endpoint = "dysmsapi.aliyuncs.com";
        return new Client(config);
    }

    public static void main(String[] args_) {
        try {
            Client client = Sample.createClient();
            SendMessageToGlobeRequest sendMessageToGlobeRequest = new SendMessageToGlobeRequest()
                    .setTo("8521245567****")
                    .setMessage("Hello");
            RuntimeOptions runtime = new RuntimeOptions();

            SendMessageToGlobeResponse sendMessageToGlobeResponse = client.sendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);
            System.out.println(new Gson().toJson(sendMessageToGlobeResponse.body));
        } catch (TeaUnretryableException ue) {
            // Only a printing example. Please be careful about exception handling and do not ignore exceptions directly in engineering projects.
            ue.printStackTrace();
            // print error message
            System.out.println(ue.getMessage());
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            // Only a printing example. Please be careful about exception handling and do not ignore exceptions directly in engineering projects.
            e.printStackTrace();
            // print error message
            System.out.println(e.getCode());
            System.out.println(e.getMessage());
            System.out.println(e.getData());
        } catch (Exception e) {
            // Only a printing example. Please be careful about exception handling and do not ignore exceptions directly in engineering projects.
            e.printStackTrace();
        }
    }
}

Advance arayüzü ile dosya yükleme

Bazı ürünler (örneğin, Image Search, Visual Intelligence API) standart OpenAPI'leri üzerinden doğrudan dosya yüklemeyi desteklemez. Bunun yerine bir dosya akışı iletmek için Advance arayüzünü kullanın. Cloud ürünü, yüklenen dosyayı geçici olarak Alibaba Cloud OSS içinde (varsayılan bölge: cn-shanghai) depolar ve buradan okur. Aşağıdaki örnekte Visual Intelligence API - Face and Body hizmetinden DetectBodyCount kullanılmaktadır:

Not

OSS'deki geçici dosyalar periyodik olarak temizlenir.

İstek istemcisini başlatın

Hem regionId hem de endpoint değerlerini ayarlayın. regionId değeri, geçici dosya depolama için kullanılan OSS bölgesini belirler. regionId ayarlanmazsa ürün ile OSS arasında bölge uyumsuzluğu nedeniyle zaman aşımları oluşabilir.

public static com.aliyun.facebody20191230.Client createClient() throws Exception {
     com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
             // Required. System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID") gets the AccessKey ID from the environment variable.
             .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
             // Required. System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET") gets the AccessKey secret from the environment variable.
             .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
     config.regionId = "cn-shanghai";
     config.endpoint = "facebody.cn-shanghai.aliyuncs.com";
     return new com.aliyun.facebody20191230.Client(config);
}

İstek nesnesi oluşturun

Dosya akışını iletmek için bir <OpenAPIName>AdvanceRequest nesnesi oluşturun. Parametre adları ve türleri için <OpenAPIName>AdvanceRequest kaynak dosyasını kontrol edin. Örneğin, DetectBodyCountAdvanceRequest türünde InputStream olan imageURLObject parametresini kabul eder.
```
com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest detectBodyCountAdvance = new com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest()
        .setImageURLObject(Files.newInputStream(Paths.get("<FILE_PATH>"))); // Replace <FILE_PATH> with the actual file path.
```

İsteği başlatın

İsteği göndermek için <apiName>Advance yöntemini çağırın.

com.aliyun.facebody20191230.Client client = createClient();
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
// Initiate the request.
com.aliyun.facebody20191230.models.DetectBodyCountResponse resp = client.detectBodyCountAdvance(detectBodyCountAdvance, runtime);

Tam kod örneğini görüntüle

/**
 * <dependency>
 *   <groupId>com.aliyun</groupId>
 *   <artifactId>facebody20191230</artifactId>
 *   <version>5.1.2</version>
 * </dependency>
 */

import com.aliyun.tea.*;
import com.google.gson.Gson;
import java.nio.file.Files;
import java.nio.file.Paths;

public class Sample {

    public static com.aliyun.facebody20191230.Client createClient() throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID") gets the AccessKey ID from the environment variable.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET") gets the AccessKey secret from the environment variable.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.regionId = "cn-shanghai";
        config.endpoint = "facebody.cn-shanghai.aliyuncs.com";
        return new com.aliyun.facebody20191230.Client(config);
    }

    public static void main(String[] args_) {
        try {
            com.aliyun.facebody20191230.Client client = Sample.createClient();
            com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest detectBodyCountAdvance = new com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest()
                    .setImageURLObject(Files.newInputStream(Paths.get("<FILE_PATH>")));  // Replace <FILE_PATH> with the actual file path.
            com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
            com.aliyun.facebody20191230.models.DetectBodyCountResponse resp = client.detectBodyCountAdvance(detectBodyCountAdvance, runtime);
            System.out.println(new Gson().toJson(resp.body));
        } catch (TeaUnretryableException ue) {
            ue.printStackTrace();
            // Print the error message.
            System.out.println(ue.getMessage());
            // Print the request record to query the request information when an error occurs.
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            e.printStackTrace();
            // Print the error code.
            System.out.println(e.getCode());
            // Print the error message, which includes the RequestId.
            System.out.println(e.getMessage());
            // Print the specific error content returned by the server.
            System.out.println(e.getData());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

SSS

Bir OpenAPI'yi çağırırken "You are not authorized to perform this operation." hata mesajı döndürülüyor.

Neden: AccessKey'inizle ilişkili RAM kullanıcısı gerekli API izinlerine sahip değil.

Çözüm: RAM kullanıcısına gerekli izinleri verin. RAM kullanıcısına izin verme.

Örneğin, SendMessageToGlobe API'sine yetki vermek için aşağıdaki özel ilkeyi oluşturun:
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "dysms:SendMessageToGlobe",
      "Resource": "*"
    }
  ]
}
```
Bir OpenAPI'yi çağırırken "The specified endpoint can't operate this region." hata mesajı döndürülüyor.

Neden: Belirtilen uç nokta hedef bölgeyi desteklemiyor.

Çözüm: Uç noktayı Uç nokta yapılandırması konusunda açıklandığı şekilde güncelleyin ve tekrar deneyin.
Bir OpenAPI'yi çağırırken "java.lang.NullPointerException..." hata mesajı döndürülüyor.

Neden: AccessKey'iniz doğru şekilde iletilmedi.

Çözüm: İstemci başlatma sırasında AccessKey'in doğru şekilde iletildiğini doğrulayın. System.getenv("XXX") ifadesi XXX değerini ortam değişkenlerinden okur.

Ek sorun giderme bilgileri: SSS.