Un guide sur Google-Http-Client

1. Vue d'ensemble

Dans cet article, nous examinerons la bibliothèque cliente HTTP de Google pour Java, qui est une bibliothèque rapide et bien abstraite pour accéder à toutes les ressources via le protocole de connexion HTTP.

Les principales caractéristiques du client sont:

  • une couche d'abstraction HTTP qui vous permet de découpler toute bibliothèque de bas niveau
  • modèles d'analyse JSON et XML rapides, efficaces et flexibles de la réponse HTTP et du contenu de la requête
  • annotations et abstractions faciles à utiliser pour les mappages de ressources HTTP

La bibliothèque peut également être utilisée dans Java 5 et au-dessus, ce qui en fait un choix considérable pour les projets hérités (SE et EE).

Dans cet article, nous allons développer une application simple qui se connectera à l'API GitHub et récupérera les utilisateurs , tout en couvrant certaines des fonctionnalités les plus intéressantes de la bibliothèque.

2. Dépendances de Maven

Pour utiliser la bibliothèque, nous avons besoin de la dépendance google-http-client :

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

La dernière version est disponible sur Maven Central.

3. Faire une demande simple

Commençons par faire une simple requête GET sur la page GitHub pour montrer comment le client Google Http fonctionne prêt à l'emploi:

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

Pour faire la demande la plus simple, nous aurons besoin d'au moins:

  • HttpRequestFactory ceci est utilisé pour construire nos requêtes
  • HttpTransport une abstraction de la couche de transport HTTP de bas niveau
  • GenericUrl une classe qui encapsule l'URL
  • HttpRequest gère l'exécution réelle de la requête

Nous allons passer en revue tout cela et un exemple plus complexe avec une API réelle qui renvoie un format JSON dans les sections suivantes.

4. Transport HTTP enfichable

La bibliothèque a une classe HttpTransport bien abstraite qui nous permet de construire dessus et de passer à la bibliothèque de transport HTTP de bas niveau sous-jacente de choix :

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

Dans cet exemple, nous utilisons NetHttpTransport , qui est basé sur la HttpURLConnection qui se trouve dans tous les SDK Java. C'est un bon choix de départ car il est bien connu et fiable.

Bien sûr, il peut y avoir le cas où nous avons besoin d'une personnalisation avancée, et donc l'exigence d'une bibliothèque de bas niveau plus complexe.

Pour ce genre de cas, il y a le ApacheHttpTransport:

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

Le ApacheHttpTransport est basé sur Apache populaire HttpClient qui comprend une grande variété de choix pour les connexions configure.

De plus, la bibliothèque offre la possibilité de créer votre implémentation de bas niveau, ce qui la rend très flexible.

5. Analyse JSON

Le client Http Google inclut une autre abstraction pour l'analyse JSON. Un avantage majeur de ceci est que le choix de la bibliothèque d'analyse de bas niveau est interchangeable .

Il y a trois choix intégrés, qui étendent tous JsonFactory, et il inclut également la possibilité d'implémenter le nôtre.

5.1. Bibliothèque d'analyse interchangeable

Dans notre exemple, nous allons utiliser l'implémentation Jackson2, qui nécessite la dépendance google-http-client-jackson2 :

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

Suite à cela, nous pouvons maintenant inclure la JsonFactory:

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

Le JacksonFactory est la plus rapide et la bibliothèque populaire pour les opérations parsing / sérialisation.

Cela se fait au détriment de la taille de la bibliothèque (ce qui pourrait être un problème dans certaines situations). Pour cette raison, Google fournit également GsonFactory , qui est une implémentation de la bibliothèque Google GSON, une bibliothèque d'analyse JSON légère.

Il y a aussi la possibilité d'écrire notre implémentation d'analyseur de bas niveau.

5.2. L' annotation @ Key

Nous pouvons utiliser l' annotation @Key pour indiquer les champs qui doivent être analysés ou sérialisés vers JSON:

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

Ici, nous faisons une abstraction utilisateur , que nous recevons par lots de l'API GitHub (nous reviendrons à l'analyse réelle plus loin dans cet article) .

Veuillez noter que les champs qui n'ont pas l' annotation @Key sont considérés comme internes et ne sont pas analysés ou sérialisés vers JSON . De plus, la visibilité des champs n'a pas d'importance, pas plus que l'existence des méthodes getter ou setter.

Nous pouvons spécifier la valeur de l' annotation @Key , pour la mapper à la clé JSON correcte.

5.3. GenericJson

Seuls les champs que nous déclarons et marquons comme @Key sont analysés.

Pour conserver l'autre contenu, nous pouvons déclarer notre classe pour étendre GenericJson:

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

GenericJson implémente l' interface Map , ce qui signifie que nous pouvons utiliser les méthodes get et put pour définir / obtenir le contenu JSON dans la requête / réponse.

6. Passer l'appel

Pour se connecter à un point de terminaison avec le client Http Google, nous aurons besoin d'une HttpRequestFactory , qui sera configurée avec nos abstractions précédentes HttpTransport et JsonFactory:

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)); }); } }

La prochaine chose dont nous aurons besoin est une URL à laquelle nous connecter. La bibliothèque gère cela comme une classe étendant GenericUrl sur laquelle tout champ déclaré est traité comme un paramètre de requête:

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

Ici, dans notre GitHubUrl, nous déclarons la propriété per_page pour indiquer le nombre d'utilisateurs que nous souhaitons en un seul appel à l'API GitHub.

Continuons à construire notre appel en utilisant le 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.

Comme toujours, le code source complet de ce didacticiel est disponible à l'adresse over sur GitHub.