Documentation

You are viewing the documentation for the 2.3.x release series. The latest stable release series is 2.5.3.

§Play WS API

Bazen Play uygulaması içinde diğer HTTP servisleri çağırmak isteriz. Play asenkron HTTP istekler yapmayı sağlayan, WS library ile bunu destekler.

WS API’yi kullanırken iki önemli parça vardır: istek yapmak ve cevabı işlemek. Öncelikle nasıl GET ve POST HTTP istekleri yapılır onu tartışacağız, ardından WS’den gelen cevabı işlemeyi göstereceğiz. Sonunda, bazı ortak kullanım durumlarını tartışacağız.

§İstek Yapmak

WS kullanmak için, öncelikle build.sbt dosyasına javaWs eklenmelidir:

libraryDependencies ++= Seq(
  javaWs
)

Ardından, devamı belirtilmelidir:

import play.libs.ws.*;
import play.libs.F.Function;
import play.libs.F.Promise;

HTTP isteği oluşturmak için, WS.url() ile bağlantıyı belirterek başlayın.

WSRequestHolder holder = WS.url("http://example.com");

Bu başlık ayarları gibi çeşitli HTTP özelliklerini belirmek için kullanabileceğiniz WSRequestHolder döndürecektir. Karışık istekler oluşturmak için birlikte zincir çağrılar yapabilirsiniz.

WSRequestHolder complexHolder = holder.setHeader("headerKey", "headerValue")
        .setTimeout(1000)
        .setQueryParameter("paramKey", "paramValue");

Kullanmak istediğiniz HTTP methoduna karşılık gelen bir methodu çağırarak sona erdirebilirsiniz. Bu zinciri sonlandıracaktır ve WSRequestHolder’da oluşturulan tüm seçenekleri kullanacaktır.

Promise<WSResponse> responsePromise = complexHolder.get();

WSResponse’un sunucudan dönen veriyi içerdiği Promise<WSResponse> döndürür.

§Doğrulamalı istekler

Eğer HTTP doğrulamasına ihticacınız varsa, kullanıcı adı, şifre ve WSAuthScheme kullanarak kurucunun içinde belirtebilirsiniz. WSAuthScheme için seçenekler BASIC, DIGEST, KERBEROS, NONE, NTLM, ve SPNEGO’dur.

WS.url(url).setAuth("user", "password", WSAuthScheme.BASIC).get();

§Takip yönlendirmeli istekler

HTTP çağrısının sonucu 302 veya 301 yönlendirmesi ise, tekrar cağrı yapmadan bu yönlendirmeyi takip edebilirsiniz.

WS.url(url).setFollowRedirects(true).get();

§Sorgu parametreli istekler

İstek için sorgu parametreleri belirleyebilirsiniz.

WS.url(url).setQueryParameter("paramKey", "paramValue");

§Ek başlıklı istekler

WS.url(url).setHeader("headerKey", "headerValue").get();

Örnek olarak, belirli formatta yalın metin gönderiyorsanız, içerik tipini açıkca belirmek isteyebilirsiniz.

WS.url(url).setHeader("Content-Type", "application/json").post(jsonString);
// OR
WS.url(url).setContentType("application/json").post(jsonString);

§Zaman aşımlı istek

İstek için zaman aşımı belirmek isterseniz, setTimeout kullanarak milisaniye olarak zaman aşımını belirtebilirsiniz.

WS.url(url).setTimeout(1000).get();

§Form verisi göndermek

url-form-encoded veri göndermek için uygun bir başlık ve biçimlendirilmiş veri ayarlayabilirsiniz.

WS.url(url).setContentType("application/x-www-form-urlencoded")
        .post("key1=value1&key2=value2");

§JSON veri göndermek

JSON verisi göndermek için en kolay yol JSON library kullanmaktır.

import com.fasterxml.jackson.databind.JsonNode;
import play.libs.Json;
JsonNode json = Json.newObject()
        .put("key1", "value1")
        .put("key2", "value2");

WS.url(url).post(json);

§Cevabı işlemek

WSResponse ile çalışmak Promise içinde planlanarak halledilir.

§Cevabı JSON olarak işlemek

response.asJson() çağırarak, cevabı JsonNode olarak işleyebilirsiniz.

Java
Promise<JsonNode> jsonPromise = WS.url(url).get().map(
        new Function<WSResponse, JsonNode>() {
            public JsonNode apply(WSResponse response) {
                JsonNode json = response.asJson();
                return json;
            }
        }
);
Java 8
Promise<JsonNode> jsonPromise = WS.url(url).get().map(response -> {
    return response.asJson();
});

§Cevabı XML olarak işlemek

Benzer bir şekilde, response.asXml() çağırarak cevabı XML olarak işleyebilirsiniz.

Java
Promise<Document> documentPromise = WS.url(url).get().map(
        new Function<WSResponse, Document>() {
            public Document apply(WSResponse response) {
                Document xml = response.asXml();
                return xml;
            }
        }
);
Java 8
Promise<Document> documentPromise = WS.url(url).get().map(response -> {
    return response.asXml();
});

§Büyük cevapları işlemek

Büyük dosya veya döküman indirirken, WS cevap gövdesini InputStream olarak almanıza izin verir, böylece veriyi bütün içeriği bir kerede belleğe yüklemeden işleyebilirsiniz.

Java
final Promise<File> filePromise = WS.url(url).get().map(
        new Function<WSResponse, File>() {
            public File apply(WSResponse response) throws Throwable {

                InputStream inputStream = null;
                OutputStream outputStream = null;
                try {
                    inputStream = response.getBodyAsStream();

                    // write the inputStream to a File
                    final File file = new File("/tmp/response.txt");
                    outputStream = new FileOutputStream(file);

                    int read = 0;
                    byte[] buffer = new byte[1024];

                    while ((read = inputStream.read(buffer)) != -1) {
                        outputStream.write(buffer, 0, read);
                    }

                    return file;
                } catch (IOException e) {
                    throw e;
                } finally {
                    if (inputStream != null) {inputStream.close();}
                    if (outputStream != null) {outputStream.close();}
                }

            }
        }
);
Java 8
Promise<File> filePromise = WS.url(url).get().map(response -> {
    InputStream inputStream = null;
    OutputStream outputStream = null;
    try {
        inputStream = response.getBodyAsStream();
    
        // write the inputStream to a File
        final File file = new File("/tmp/response.txt");
        outputStream = new FileOutputStream(file);
    
        int read = 0;
        byte[] buffer = new byte[1024];

        while ((read = inputStream.read(buffer)) != -1) {
            outputStream.write(buffer, 0, read);
        }
  
        return file;  
    } catch (IOException e) {
        throw e;
    } finally {
        if (inputStream != null) {inputStream.close();}
        if (outputStream != null) {outputStream.close();}
    } 
});

Bu örnek cevap gövdesini okuyup, arabelleklenen arttırımlarla dosyaya yazacaktır.

§Ortak Motifler ve Kullanım Durumları

§WS Çağrıları Zincirlemek

flatMap kullanarak zincir WS çağrıları yapabilirsiniz.

Java
final Promise<WSResponse> responseThreePromise = WS.url(urlOne).get().flatMap(
        new Function<WSResponse, Promise<WSResponse>>() {
            public Promise<WSResponse> apply(WSResponse responseOne) {
                String urlTwo = responseOne.getBody();
                return WS.url(urlTwo).get().flatMap(
                        new Function<WSResponse, Promise<WSResponse>>() {
                            public Promise<WSResponse> apply(WSResponse responseTwo) {
                                String urlThree = responseTwo.getBody();
                                return WS.url(urlThree).get();
                            }
                        }
                );
            }
        }
);
Java 8
final Promise<WSResponse> responseThreePromise = WS.url(urlOne).get()
    .flatMap(responseOne -> WS.url(responseOne.getBody()).get())
    .flatMap(responseTwo -> WS.url(responseTwo.getBody()).get());

§İstisnaları Kurtarmak

Eğer istek içinde istisna durumları kurtarmak istiyorsanız, temcilci cevap için recover veya recoverWith kullanınız.

Java
Promise<WSResponse> responsePromise = WS.url("http://example.com").get();
Promise<WSResponse> recoverPromise = responsePromise.recoverWith(new Function<Throwable, Promise<WSResponse>>() {
    @Override
    public Promise<WSResponse> apply(Throwable throwable) throws Throwable {
        return WS.url("http://backup.example.com").get();
    }
});
Java 8
Promise<WSResponse> responsePromise = WS.url("http://example.com").get();
Promise<WSResponse> recoverPromise = responsePromise.recoverWith(throwable ->
    WS.url("http://backup.example.com").get()
);

§Controller Kullanımı

Promise<WSResponse>’u Promise<Result>’a dönüştürerek Handling Asynchronous Results’da tanımlanmış asenkron action motifi kullanarak Play sunucusu tarafından direkt idare edilmesini sağlayabilirsiniz.

Java
public static Promise<Result> index() {
    final Promise<Result> resultPromise = WS.url(feedUrl).get().map(
            new Function<WSResponse, Result>() {
                public Result apply(WSResponse response) {
                    return ok("Feed title:" + response.asJson().findPath("title"));
                }
            }
    );
    return resultPromise;
}
Java 8
public static Promise<Result> index() {
    return WS.url(feedUrl).get().map(response ->
        ok("Feed title: " + response.asJson().findPath("title").asText())
    );
}

§WSClient kullanarak

WSClient AsyncHttpClient temilinin kapsayıcısıdır. Çeşitli profillere sahip çoklu istemci tanımlamak veya taklit istek kullanımı için kullanışlıdır

Varsayılan istemci WS sınıfından çağırılabilir:

WSClient client = WS.client();

WS istemcisini doğrudan koddan tanımlayabilir ve bunu istek yapmak için kullanabilirsiniz.

 // Set up the client config (you can also use a parser here):
 scala.Option<Object> none = scala.None$.empty();
 scala.Option<String> noneString = scala.None$.empty();
 scala.Option<SSLConfig> noneSSLConfig = scala.None$.empty();
 WSClientConfig clientConfig = new DefaultWSClientConfig(
         none, // connectionTimeout
         none, // idleTimeout
         none, // requestTimeout
         none, // followRedirects
         none, // useProxyProperties
         noneString, // userAgent
         none, // compressionEnabled
         none, // acceptAnyCertificate
         noneSSLConfig);

 // Build a secure config out of the client config and the ning builder:
 AsyncHttpClientConfig.Builder asyncHttpClientBuilder = new AsyncHttpClientConfig.Builder();
 NingAsyncHttpClientConfigBuilder secureBuilder = new NingAsyncHttpClientConfigBuilder(clientConfig,
         asyncHttpClientBuilder);
 AsyncHttpClientConfig secureDefaults = secureBuilder.build();

 // You can directly use the builder for specific options once you have secure TLS defaults...
AsyncHttpClientConfig customConfig = new AsyncHttpClientConfig.Builder(secureDefaults)
                 .setProxyServer(new com.ning.http.client.ProxyServer("127.0.0.1", 38080))
                 .setCompressionEnabled(true)
                 .build();
 WSClient customClient = new play.libs.ws.ning.NingWSClient(customConfig);

 Promise<WSResponse> responsePromise = customClient.url("http://example.com/feed").get();

NOTE: NingWSClient nesnesini temsil ediyorsanız, WS eklenti sistemini kullanmaz, ve bu yüzden Application.onStop‘da otomatik olarak kapatılmayacaktır. Bunun yerine, işlemler tamamlanınca client.close() kullanarak elle kapatılmalıdır. Bu AsyncHttpClient tarafından kullanılan ThreadPoolExecutor’ın temelini serbest bırakacaktır. İstemci kapatırken oluşan bozukluk yetersiz bellek hatasına sebep olabilir. (özellikle uygulamanıcı geliştirici modunda sıklıkla kapatıp açıyorsanız).

AsyncHttpClient’in temelinede erişebilirsiniz.

com.ning.http.client.AsyncHttpClient underlyingClient =
        (com.ning.http.client.AsyncHttpClient) WS.client().getUnderlying();

Birkaç durumda bu önemlidir. WS’nin istemciye erişmesi gereken birkaç kısıtlaması vardır.

§WS Yapılandırma

WS istemcisini yapılandırmak için aşağıdaki özellikleri application.conf içinde kullanınız

§Zaman Aşımları

WS’de 3 farklı zaman aşımı vardır. Zaman aşımına uğramak WS isteğinin kesilmesine yol açar.

İstek zaman aşımı belirli bağlantılarda setTimeout() kullanılarak geçersiz kılınabilir. (“İstek Yapmak” bölümüne bakınız)

§WS’yi SSL ile Yapılandırma

WS’yi HTTP isteklerini SSL/TLS (HTTPS) üzerinden yapılandırmak için, lütfen WS SSL Yapılandırma’e bakınız.

Sonraki: OpenID servislerine bağlanma


Dokümantasyonun bu çevirisi Play ekibi tarafından yapılmamaktadır. Eğer bir hata bulduysanız, bu sayfanın kaynak kodu burada bulunmaktadır. Dokümantasyon yönergelerini okuduktan sonra lütfen katkı yapmaktan çekinmeyin.