Panduan untuk Google-Http-Client

1. Gambaran keseluruhan

Dalam artikel ini, kita akan melihat Perpustakaan Pelanggan HTTP Google untuk Java, yang merupakan perpustakaan cepat dan abstrak untuk mengakses sumber daya melalui protokol sambungan HTTP.

Ciri utama pelanggan adalah:

  • lapisan abstraksi HTTP yang membolehkan anda mencabut perpustakaan tahap rendah
  • model penghuraian dan permintaan permintaan JSON dan XML yang pantas, cekap dan fleksibel
  • anotasi dan pengabstrakan yang mudah digunakan untuk pemetaan sumber HTTP

Perpustakaan juga dapat digunakan di Java 5 dan ke atas, menjadikannya pilihan yang cukup besar untuk projek warisan (SE dan EE).

Dalam artikel ini, kami akan mengembangkan aplikasi sederhana yang akan terhubung ke GitHub API dan mengambil pengguna , sambil merangkumi beberapa ciri perpustakaan yang paling menarik.

2. Pergantungan Maven

Untuk menggunakan perpustakaan, kami memerlukan kebergantungan klien google-http :

 com.google.http-client google-http-client 1.23.0 

Versi terbaru boleh didapati di Maven Central.

3. Membuat Permintaan Mudah

Mari mulakan dengan membuat permintaan GET yang mudah ke halaman GitHub untuk menunjukkan bagaimana Klien Google Http berfungsi di luar kotak:

HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(); HttpRequest request = requestFactory.buildGetRequest( new GenericUrl("//github.com")); String rawResponse = request.execute().parseAsString()

Untuk membuat permintaan paling mudah, kami memerlukan sekurang-kurangnya:

  • HttpRequestFactory ini digunakan untuk membina permintaan kami
  • HttpTransport pengabstrakan lapisan pengangkutan HTTP tahap rendah
  • GenericUrl kelas yang membungkus Url
  • HttpRequest menangani pelaksanaan sebenar permintaan

Kami akan melalui semua ini dan contoh yang lebih kompleks dengan API sebenar yang mengembalikan format JSON di bahagian berikut.

4. Pengangkutan HTTP yang boleh dipasang

Perpustakaan mempunyai kelas HttpTransport yang diabstrak dengan baik yang membolehkan kami membangun di atasnya dan menukar ke pilihan perpustakaan pengangkutan HTTP tahap rendah yang mendasari :

public class GitHubExample { static HttpTransport HTTP_TRANSPORT = new NetHttpTransport(); }

Dalam contoh ini, kami menggunakan NetHttpTransport , yang berdasarkan pada HttpURLConnection yang terdapat di semua SDK Java. Ini adalah pilihan permulaan yang baik kerana ia terkenal dan boleh dipercayai.

Tentu saja, mungkin ada kes di mana kita memerlukan penyesuaian lanjutan, dan dengan itu keperluan perpustakaan tingkat rendah yang lebih kompleks.

Untuk kes seperti ini, terdapat ApacheHttpTransport:

public class GitHubExample { static HttpTransport HTTP_TRANSPORT = new ApacheHttpTransport(); }

The ApacheHttpTransport adalah berdasarkan Apache popular HttpClient yang merangkumi pelbagai jenis pilihan untuk sambungan configure.

Selain itu, perpustakaan menyediakan pilihan untuk membina pelaksanaan tahap rendah anda, menjadikannya sangat fleksibel.

5. JSON Menghuraikan

Pelanggan Http Google merangkumi pengabaian lain untuk menguraikan JSON. Kelebihan utama ini adalah bahawa pilihan parsing parsing peringkat rendah boleh ditukar ganti .

Ada tiga pilihan bawaan, semuanya memperluas JsonFactory, dan ini juga merangkumi kemungkinan untuk melaksanakan pilihan kita sendiri.

5.1. Perpustakaan Penguraian yang Boleh Ditukar

Dalam contoh kami, kami akan menggunakan pelaksanaan Jackson2, yang memerlukan pergantungan google-http-client-jackson2 :

 com.google.http-client google-http-client-jackson2 1.23.0 

Berikut ini, kita sekarang boleh memasukkan JsonFactory:

public class GitHubExample { static HttpTransport HTTP_TRANSPORT = new NetHttpTransport(); staticJsonFactory JSON_FACTORY = new JacksonFactory(); }

The JacksonFactory adalah perpustakaan yang paling cepat dan paling popular untuk operasi parsing / serialization.

Ini datang dengan kos ukuran perpustakaan (yang mungkin menjadi perhatian dalam situasi tertentu). Atas sebab ini, Google juga menyediakan GsonFactory , yang merupakan penerapan perpustakaan Google GSON, perpustakaan penghuraian JSON ringan.

Terdapat juga kemungkinan menulis pelaksanaan penghurai tahap rendah kami.

5.2. Anotasi Utama @

Kami boleh menggunakan anotasi @Key untuk menunjukkan medan yang perlu dihuraikan dari atau bersiri ke JSON:

public class User { @Key private String login; @Key private long id; @Key("email") private String email; // standard getters and setters }

Di sini kami membuat abstraksi Pengguna , yang kami terima secara bertahap dari GitHub API (kami akan sampai ke penghuraian yang sebenarnya dalam artikel ini) .

Harap maklum bahawa medan yang tidak mempunyai anotasi @Key dianggap dalaman dan tidak dihuraikan dari atau bersiri ke JSON . Juga, penglihatan ladang tidak menjadi masalah, dan juga keberadaan kaedah mendapatkan atau menetapkan

Kita dapat menentukan nilai anotasi @Key , untuk memetakannya ke kunci JSON yang betul.

5.3. GenerikJson

Hanya medan yang kami nyatakan, dan tandakan sebagai @Key diuraikan.

Untuk mengekalkan kandungan lain, kami dapat menyatakan kelas kami untuk memperluas GenericJson:

public class User extends GenericJson { //... }

GenericJson mengimplementasikan antara muka Peta , yang berarti kita dapat menggunakan metode get and let untuk menetapkan / mendapatkan konten JSON dalam permintaan / respons.

6. Membuat Panggilan

Untuk menyambung ke titik akhir dengan Pelanggan Google Http, kami memerlukan HttpRequestFactory , yang akan dikonfigurasi dengan abstraksi HttpTransport dan JsonFactory sebelumnya :

public class GitHubExample { static HttpTransport HTTP_TRANSPORT = new NetHttpTransport(); static JsonFactory JSON_FACTORY = new JacksonFactory(); private static void run() throws Exception { HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory( (HttpRequest request) -> { request.setParser(new JsonObjectParser(JSON_FACTORY)); }); } }

Perkara seterusnya yang kita perlukan adalah URL untuk disambungkan. Perpustakaan menangani ini sebagai kelas yang meluaskan GenericUrl di mana bidang yang dinyatakan dinyatakan sebagai parameter pertanyaan:

public class GitHubUrl extends GenericUrl { public GitHubUrl(String encodedUrl) { super(encodedUrl); } @Key public int per_page; }

Di sini di GitHubUrl kami , kami menyatakan harta per_page untuk menunjukkan berapa banyak pengguna yang kami mahukan dalam satu panggilan ke GitHub API.

Mari terus membina panggilan kami menggunakan GitHubUrl:

private static void run() throws Exception { HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory( (HttpRequest request) -> { request.setParser(new JsonObjectParser(JSON_FACTORY)); }); GitHubUrl url = new GitHubUrl("//api.github.com/users"); url.per_page = 10; HttpRequest request = requestFactory.buildGetRequest(url); Type type = new TypeToken
    
     () {}.getType(); List users = (List)request .execute() .parseAs(type); }
    

Notice how we specify how many users we'll need for the API call, and then we build the request with the HttpRequestFactory.

Following this, since the GitHub API's response contains a list of users, we need to provide a complex Type, which is a List.

Then, on the last line, we make the call and parse the response to a list of our User class.

7. Custom Headers

One thing we usually do when making an API request is to include some kind of custom header or even a modified one:

HttpHeaders headers = request.getHeaders(); headers.setUserAgent("Baeldung Client"); headers.set("Time-Zone", "Europe/Amsterdam");

We do this by getting the HttpHeaders after we've created our request but before executing it and adding the necessary values.

Please be aware that the Google Http Client includes some headers as special methods. The User-Agent header for example, if we try to include it with just the set method it would throw an error.

8. Exponential Backoff

Another important feature of the Google Http Client is the possibility to retry requests based on certain status codes and thresholds.

We can include our exponential backoff settings right after we've created our request object:

ExponentialBackOff backoff = new ExponentialBackOff.Builder() .setInitialIntervalMillis(500) .setMaxElapsedTimeMillis(900000) .setMaxIntervalMillis(6000) .setMultiplier(1.5) .setRandomizationFactor(0.5) .build(); request.setUnsuccessfulResponseHandler( new HttpBackOffUnsuccessfulResponseHandler(backoff));

Exponential Backoff is turned off by default in HttpRequest, so we must include an instance of HttpUnsuccessfulResponseHandler to the HttpRequest to activate it.

9. Logging

The Google Http Client uses java.util.logging.Logger for logging HTTP request and response details, including URL, headers, and content.

Commonly, logging is managed using a logging.properties file:

handlers = java.util.logging.ConsoleHandler java.util.logging.ConsoleHandler.level = ALL com.google.api.client.http.level = ALL

In our example we use ConsoleHandler, but it's also possible to choose the FileHandler.

The properties file configures the operation of the JDK logging facility. This config file can be specified as a system property:

-Djava.util.logging.config.file=logging.properties

So after setting the file and system property, the library will produce a log like the following:

-------------- REQUEST -------------- GET //api.github.com/users?page=1&per_page=10 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.23.0 (gzip) Nov 12, 2017 6:43:15 PM com.google.api.client.http.HttpRequest execute curl -v --compressed -H 'Accept-Encoding: gzip' -H 'User-Agent: Google-HTTP-Java-Client/1.23.0 (gzip)' -- '//api.github.com/users?page=1&per_page=10' Nov 12, 2017 6:43:16 PM com.google.api.client.http.HttpResponse -------------- RESPONSE -------------- HTTP/1.1 200 OK Status: 200 OK Transfer-Encoding: chunked Server: GitHub.com Access-Control-Allow-Origin: * ... Link: ; rel="next", ; rel="first" X-GitHub-Request-Id: 8D6A:1B54F:3377D97:3E37B36:5A08DC93 Content-Type: application/json; charset=utf-8 ...

10. Conclusion

In this tutorial, we've shown the Google HTTP Client Library for Java and its more useful features. Their Github contains more information about it as well as the source code of the library.

Seperti biasa, kod sumber penuh tutorial ini terdapat di GitHub.