En guide til Google-Http-Client

1. Oversikt

I denne artikkelen ser vi på Google HTTP Client Library for Java, som er et raskt, godt abstrakt bibliotek for tilgang til ressurser via HTTP-tilkoblingsprotokollen.

Hovedtrekkene til klienten er:

  • et HTTP-abstraksjonslag som lar deg koble fra ethvert lavnivåbibliotek
  • raske, effektive og fleksible JSON- og XML-analyseringsmodeller av HTTP-svar og forespørsel om innhold
  • enkle å bruke merknader og abstraksjoner for HTTP-ressurskartlegginger

Biblioteket kan også brukes i Java 5 og nyere, noe som gjør det til et betydelig valg for eldre (SE og EE) prosjekter.

I denne artikkelen skal vi utvikle en enkel applikasjon som vil koble til GitHub API og hente brukere, mens dekker noen av de mest interessante funksjonene i biblioteket.

2. Maven-avhengigheter

For å bruke biblioteket trenger vi google-http-klient avhengighet:

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

Den siste versjonen finner du på Maven Central.

3. Lage en enkel forespørsel

La oss starte med å lage en enkel GET-forespørsel til GitHub-siden for å vise hvordan Google Http-klienten fungerer ut av boksen:

HttpRequestFactory requestFactory = ny NetHttpTransport (). CreateRequestFactory (); HttpRequest-forespørsel = requestFactory.buildGetRequest (ny GenericUrl ("// github.com")); String rawResponse = forespørsel. Utfør (). ParseAsString ()

For å gjøre den enkleste forespørselen trenger vi minst:

  • HttpRequestFactory dette brukes til å bygge våre forespørsler
  • HttpTransport en abstraksjon av HTTP-transportlaget på lavt nivå
  • GenericUrl en klasse som pakker inn nettadressen
  • HttpForespørsel håndterer den faktiske gjennomføringen av forespørselen

Vi vil gå gjennom alle disse og et mer komplekst eksempel med en faktisk API som returnerer et JSON-format i de følgende avsnittene.

4. Pluggbar HTTP-transport

Biblioteket har et godt abstrakt HttpTransport klasse som lar oss bygge på toppen av den og endre til det underliggende lavnivå HTTP-transportbiblioteket du velger:

offentlig klasse GitHubExample {statisk HttpTransport HTTP_TRANSPORT = ny NetHttpTransport (); }

I dette eksemplet bruker vi NetHttpTransport, som er basert på HttpURLConnection som finnes i alle Java SDK-er. Dette er et godt startvalg siden det er kjent og pålitelig.

Selvfølgelig kan det være tilfelle der vi trenger noen avanserte tilpasninger, og dermed kravet om et mer komplekst bibliotek på lavt nivå.

For denne typen saker er det ApacheHttpTransport:

offentlig klasse GitHubExample {statisk HttpTransport HTTP_TRANSPORT = ny ApacheHttpTransport (); }

De ApacheHttpTransport er basert på den populære Apache HttpClient som inkluderer et bredt utvalg av valg for å konfigurere tilkoblinger.

I tillegg gir biblioteket muligheten til å bygge implementeringen på lavt nivå, noe som gjør den veldig fleksibel.

5. JSON Parsing

Google Http-klienten inkluderer en annen abstraksjon for JSON-parsing. En stor fordel med dette er at valget av analyseringsbibliotek på lavt nivå er utskiftbart.

Det er tre innebygde valg, som alle strekker seg JsonFactory, og det inkluderer også muligheten for å implementere våre egne.

5.1. Utskiftbart analyseringsbibliotek

I vårt eksempel skal vi bruke Jackson2-implementeringen, som krever google-http-client-jackson2 avhengighet:

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

Etter dette kan vi nå inkludere JsonFactory:

offentlig klasse GitHubExample {statisk HttpTransport HTTP_TRANSPORT = ny NetHttpTransport (); staticJsonFactory JSON_FACTORY = ny JacksonFactory (); }

De JacksonFactory er det raskeste og mest populære biblioteket for parsing / serialisering.

Dette koster biblioteksstørrelsen (som kan være en bekymring i visse situasjoner). Av denne grunn tilbyr Google også GsonFactory, som er en implementering av Google GSON-biblioteket, et lett JSON-analyseringsbibliotek.

Det er også muligheten for å skrive vår implementering av parser på lavt nivå.

5.2. @Nøkkel Kommentar

Vi kan bruke @Nøkkel kommentar for å indikere felt som må analyseres fra eller serialiseres til JSON:

offentlig klasse bruker {@ Key private String login; @ Key private lang id; @Key ("e-post") privat streng-e-post; // standard getters og setters}

Her lager vi en Bruker abstraksjon, som vi mottar i batch fra GitHub API (vi kommer til den faktiske analyseringen senere i denne artikkelen).

Vær oppmerksom på at felt som ikke har @Nøkkel merknader betraktes som interne og blir ikke analysert fra eller serialisert til JSON. Synligheten til feltene spiller ingen rolle, og heller ikke eksistensen av getter- eller settermetodene.

Vi kan spesifisere verdien på @Nøkkel merknad, for å kartlegge den til riktig JSON-nøkkel.

5.3. GenericJson

Bare feltene vi erklærer, og merker som @Nøkkel blir analysert.

For å beholde det andre innholdet kan vi erklære at klassen vår utvides GenericJson:

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

GenericJson implementerer Kart grensesnitt, noe som betyr at vi kan bruke get and put-metodene for å angi / få JSON-innhold i forespørselen / svaret.

6. Ringe

For å koble til et sluttpunkt med Google Http-klienten, trenger vi en HttpRequestFactory, som vil bli konfigurert med våre tidligere abstraksjoner HttpTransport og JsonFactory:

offentlig klasse GitHubExample {statisk HttpTransport HTTP_TRANSPORT = ny NetHttpTransport (); statisk JsonFactory JSON_FACTORY = ny JacksonFactory (); privat statisk ugyldig kjøring () kaster Unntak {HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory ((HttpRequest forespørsel) -> {request.setParser (ny JsonObjectParser (JSON_FACTORY));}); }}

Den neste tingen vi trenger er en URL å koble til. Biblioteket håndterer dette som en klasse som utvides GenericUrl som deklarert felt blir behandlet som en spørringsparameter:

offentlig klasse GitHubUrl utvider GenericUrl {offentlig GitHubUrl (streng kodetUrl) {super (kodetUrl); } @Key public int per_page; }

Her i vår GitHubUrl, vi erklærer per side egenskap for å indikere hvor mange brukere vi vil ha i en enkelt samtale til GitHub API.

La oss fortsette å bygge samtalen vår med GitHubUrl:

privat statisk ugyldig kjøring () kaster Unntak {HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory ((HttpRequest forespørsel) -> {request.setParser (ny JsonObjectParser (JSON_FACTORY));}); GitHubUrl url = new GitHubUrl ("// api.github.com/users"); url.per_page = 10; HttpRequest-forespørsel = requestFactory.buildGetRequest (url); Type type = ny TypeToken() {} .getType (); Listebrukere = (Liste) forespørsel .utfør () .parseAs (type); }

Legg merke til hvordan vi spesifiserer hvor mange brukere vi trenger for API-samtalen, og deretter bygger vi forespørselen med HttpRequestFactory.

Etter dette, siden GitHub API-svaret inneholder en liste over brukere, må vi tilby et kompleks Type, hvilken er en Liste.

Så, på siste linje, ringer vi og analyserer svaret på en liste over våre Bruker klasse.

7. Tilpassede overskrifter

En ting vi vanligvis gjør når vi sender en API-forespørsel, er å inkludere en slags tilpasset overskrift eller til og med en modifisert:

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

Vi gjør dette ved å få HttpHeaders etter at vi har opprettet forespørselen vår, men før vi utfører den og legger til de nødvendige verdiene.

Vær oppmerksom på at Google Http-klienten inneholder noen overskrifter som spesielle metoder. De Bruker agent header for eksempel, hvis vi prøver å inkludere den med bare den angitte metoden, vil det kaste en feil.

8. Eksponentiell tilbakeslag

En annen viktig funksjon i Google Http-klienten er muligheten til å prøve forespørsler på nytt basert på visse statuskoder og terskler.

Vi kan inkludere våre eksponentielle backoff-innstillinger rett etter at vi har opprettet forespørselsobjektet:

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

Eksponentiell tilbakeslag er slått av som standard i HttpForespørsel, så vi må ta med en forekomst av HttpUnsuccessfulResponseHandler til HttpForespørsel for å aktivere den.

9. Logging

Google Http-klienten bruker java.util.logging.Logger for logging av HTTP-forespørsel og svardetaljer, inkludert URL, overskrifter og innhold.

Vanligvis administreres logging ved hjelp av a logging.egenskaper fil:

håndtere = java.util.logging.ConsoleHandler java.util.logging.ConsoleHandler.level = ALLE com.google.api.client.http.level = ALL

I vårt eksempel bruker vi ConsoleHandler, men det er også mulig å velge FileHandler.

Egenskapsfilen konfigurerer driften av JDK-loggningsanlegget. Denne konfigurasjonsfilen kan spesifiseres som en systemegenskap:

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

Så etter å ha satt fil- og systemegenskapen, vil biblioteket produsere en logg som følger:

-------------- FORESPØRSEL -------------- FÅ //api.github.com/users?page=1&per_page=10 Godta-koding: gzip Brukeragent: Google-HTTP-Java-Client / 1.23.0 (gzip) 12. november 2017 18:43:15 com.google.api.client.http.HttpRequest execute curl -v --compressed -H 'Accept -Koding: gzip '-H' Brukeragent: Google-HTTP-Java-Client / 1.23.0 (gzip) '-' //api.github.com/users?page=1&per_page=10 '12. november 2017 18:43:16 com.google.api.client.http.HttpResponse -------------- SVAR -------------- HTTP / 1.1 200 OK Status: 200 OK Transfer-Encoding: chunked Server: GitHub.com Access-Control-Allow-Origin: * ... Link:; rel = "neste",; rel = "første" X-GitHub-Request-Id: 8D6A: 1B54F: 3377D97: 3E37B36: 5A08DC93 Content-Type: application / json; charset = utf-8 ...

10. Konklusjon

I denne opplæringen har vi vist Google HTTP Client Library for Java og dets mer nyttige funksjoner. Deres Github inneholder mer informasjon om det, samt kildekoden til biblioteket.

Som alltid er hele kildekoden til denne opplæringen tilgjengelig på GitHub.


$config[zx-auto] not found$config[zx-overlay] not found