En guide til Google-Http-klient
1. Oversigt
I denne artikel ser vi på Google HTTP-klientbiblioteket til Java, som er et hurtigt, godt abstrakt bibliotek til adgang til alle ressourcer via HTTP-forbindelsesprotokollen.
Klientens hovedfunktioner er:
- et HTTP-abstraktionslag, der lader dig afkoble ethvert bibliotek på lavt niveau
- hurtige, effektive og fleksible JSON- og XML-parsemodeller af HTTP-svaret og anmodningsindhold
- let at bruge annoteringer og abstraktioner til HTTP-ressourcekortlægninger
Biblioteket kan også bruges i Java 5 og nyere, hvilket gør det til et betydeligt valg til ældre (SE og EE) projekter.
I denne artikel vil vi udvikle en simpel applikation, der opretter forbindelse til GitHub API og henter brugere, mens de dækker nogle af de mest interessante funktioner i biblioteket.
2. Maven-afhængigheder
For at bruge biblioteket har vi brug for google-http-klient afhængighed:
com.google.http-client google-http-client 1.23.0 Den seneste version kan findes på Maven Central.
3. Lav en simpel anmodning
Lad os starte med at lave en simpel GET-anmodning til GitHub-siden for at vise, hvordan Google Http-klienten fungerer ud af boksen:
HttpRequestFactory requestFactory = ny NetHttpTransport (). CreateRequestFactory (); HttpRequest anmodning = requestFactory.buildGetRequest (ny GenericUrl ("// github.com")); String rawResponse = request.execute (). ParseAsString ()For at gøre den enkleste anmodning skal vi mindst bruge:
- HttpRequestFactory dette bruges til at opbygge vores anmodninger
- HttpTransport en abstraktion af HTTP-transportlaget på lavt niveau
- GenericUrl en klasse, der indpakker url
- HttpForespørgsel håndterer den faktiske udførelse af anmodningen
Vi gennemgår alle disse og et mere komplekst eksempel med en faktisk API, der returnerer et JSON-format i de følgende sektioner.
4. Tilslutbar HTTP-transport
Biblioteket har et godt abstrakt HttpTransport klasse, der giver os mulighed for at bygge oven på det og skift til det underliggende lavt niveau HTTP-transportbibliotek, du vælger:
offentlig klasse GitHubExample {statisk HttpTransport HTTP_TRANSPORT = ny NetHttpTransport (); }I dette eksempel bruger vi NetHttpTransport, som er baseret på HttpURLforbindelse der findes i alle Java SDK'er. Dette er et godt startvalg, da det er velkendt og pålideligt.
Selvfølgelig kan der være tilfældet, hvor vi har brug for avanceret tilpasning, og dermed kravet om et mere komplekst bibliotek på lavt niveau.
For denne slags sager er der ApacheHttpTransport:
offentlig klasse GitHubExample {statisk HttpTransport HTTP_TRANSPORT = ny ApacheHttpTransport (); }Det ApacheHttpTransport er baseret på den populære Apache HttpClient, som inkluderer en bred vifte af valg til konfiguration af forbindelser.
Derudover giver biblioteket mulighed for at opbygge din implementering på lavt niveau, hvilket gør den meget fleksibel.
5. JSON-parsing
Google Http-klienten inkluderer en anden abstraktion til JSON-parsing. En stor fordel ved dette er, at valget af parsingsbibliotek på lavt niveau kan udskiftes.
Der er tre indbyggede valg, som alle strækker sig JsonFabrik, og det inkluderer også muligheden for at implementere vores egne.
5.1. Udskifteligt analyseringsbibliotek
I vores eksempel skal vi bruge Jackson2-implementeringen, som kræver google-http-klient-jackson2 afhængighed:
com.google.http-client google-http-client-jackson2 1.23.0 Efter dette kan vi nu inkludere JsonFabrik:
offentlig klasse GitHubExample {statisk HttpTransport HTTP_TRANSPORT = ny NetHttpTransport (); staticJsonFactory JSON_FACTORY = ny JacksonFactory (); }Det JacksonFabrik er det hurtigste og mest populære bibliotek til parsing / serialisering.
Dette koster biblioteksstørrelsen (hvilket kan være et problem i visse situationer). Af denne grund leverer Google også GsonFactory, som er en implementering af Google GSON-biblioteket, et let JSON-parseringsbibliotek.
Der er også mulighed for at skrive vores implementering af parser på lavt niveau.
5.2. Det @Nøgle Kommentar
Vi kan bruge @Nøgle kommentar for at angive felter, der skal parses fra eller serialiseres til JSON:
offentlig klasse bruger {@Key private String login; @Nøgle privat langt id; @Key ("e-mail") privat streng-mail; // standard getters og setter}Her laver vi en Bruger abstraktion, som vi modtager i batch fra GitHub API (vi kommer til den faktiske parsing senere i denne artikel).
Bemærk, at felter, der ikke har @Nøgle annotering betragtes som intern og parses ikke fra eller serialiseres til JSON. Desuden betyder markernes synlighed ikke noget, og heller ikke eksistensen af getter- eller settermetoderne.
Vi kan specificere værdien af @Nøgle kommentar for at kortlægge den til den korrekte JSON-nøgle.
5.3. GenericJson
Kun de felter, vi erklærer og markerer som @Nøgle er analyseret.
For at bevare det andet indhold kan vi erklære, at vores klasse udvides GenericJson:
public class User udvider GenericJson {// ...}GenericJson implementerer Kort interface, hvilket betyder, at vi kan bruge get and put-metoderne til at indstille / hente JSON-indhold i anmodningen / svaret.
6. Foretagelse af opkaldet
For at oprette forbindelse til et slutpunkt med Google Http-klienten har vi brug for en HttpRequestFactory, som vil blive konfigureret med vores tidligere abstraktioner HttpTransport og JsonFabrik:
offentlig klasse GitHubExample {statisk HttpTransport HTTP_TRANSPORT = ny NetHttpTransport (); statisk JsonFactory JSON_FACTORY = ny JacksonFactory (); privat statisk ugyldig kørsel () kaster Undtagelse {HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory ((HttpRequest anmodning) -> {request.setParser (ny JsonObjectParser (JSON_FACTORY));}); }}Den næste ting, vi får brug for, er en URL til at oprette forbindelse til. Biblioteket håndterer dette som en klasse, der udvides GenericUrl hvorpå ethvert felt, der erklæres, behandles som en forespørgselsparameter:
offentlig klasse GitHubUrl udvider GenericUrl {public GitHubUrl (String encodedUrl) {super (encodedUrl); } @Key public int per_page; }Her i vores GitHubUrl, vi erklærer pr. side egenskab for at angive, hvor mange brugere vi vil have i et enkelt opkald til GitHub API.
Lad os fortsætte med at opbygge vores opkald ved hjælp af GitHubUrl:
privat statisk ugyldig kørsel () kaster Undtagelse {HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory ((HttpRequest anmodning) -> {request.setParser (ny JsonObjectParser (JSON_FACTORY));}); GitHubUrl url = ny GitHubUrl ("// api.github.com/users"); url.per_page = 10; HttpRequest anmodning = requestFactory.buildGetRequest (url); Type type = ny TypeToken() {} .getType (); Listebrugere = (Liste) anmoder om .eksekver () .parseAs (type); }
Læg mærke til, hvordan vi angiver, hvor mange brugere vi har brug for til API-opkaldet, og derefter bygger vi anmodningen med HttpRequestFactory.
Efter dette, da GitHub API's svar indeholder en liste over brugere, er vi nødt til at levere et kompleks Type, som er en Liste.
Så på den sidste linje foretager vi opkaldet og analyserer svaret på en liste over vores Bruger klasse.
7. Tilpassede overskrifter
En ting, vi normalt gør, når vi fremsætter en API-anmodning, er at inkludere en slags tilpasset header eller endda en ændret:
HttpHeaders headers = request.getHeaders (); headers.setUserAgent ("Baeldung Client"); headers.set ("Time-Zone", "Europe / Amsterdam");Vi gør dette ved at få HttpHeaders efter at vi har oprettet vores anmodning, men før vi udfører den og tilføjer de nødvendige værdier.
Vær opmærksom på, at Google Http-klienten inkluderer nogle overskrifter som specielle metoder. Det Brugeragent header for eksempel, hvis vi forsøger at inkludere det med bare den indstillede metode, ville det kaste en fejl.
8. Eksponentiel tilbagetrækning
Et andet vigtigt træk ved Google Http-klienten er muligheden for at prøve igen anmodninger baseret på bestemte statuskoder og tærskler.
Vi kan inkludere vores eksponentielle backoff-indstillinger lige efter vi har oprettet vores anmodningsobjekt:
ExponentialBackOff backoff = ny ExponentialBackOff.Builder () .setInitialIntervalMillis (500) .setMaxElapsedTimeMillis (900000) .setMaxIntervalMillis (6000) .setMultiplier (1.5) .setRandomizationFactor (0.5) .build (); request.setUnsuccessfulResponseHandler (ny HttpBackOffUnsuccessfulResponseHandler (backoff));Eksponentiel afbrydelse er som standard slået fra i HttpForespørgsel, så vi skal inkludere en forekomst af HttpUnsuccessfulResponseHandler til HttpForespørgsel for at aktivere det.
9. Logning
Google Http-klienten bruger java.util.logging.Logger til logning af HTTP-anmodning og svaroplysninger, herunder URL, headere og indhold.
Normalt administreres logning ved hjælp af en logging.properties fil:
håndtere = java.util.logging.ConsoleHandler java.util.logging.ConsoleHandler.level = ALLE com.google.api.client.http.level = ALLEI vores eksempel bruger vi ConsoleHandler, men det er også muligt at vælge FileHandler.
Egenskabsfilen konfigurerer driften af JDK-logningsfaciliteten. Denne konfigurationsfil kan angives som en systemegenskab:
-Djava.util.logging.config.file = logging.egenskaberSå efter indstilling af fil- og systemegenskab vil biblioteket producere en log som følgende:
-------------- ANMODNING -------------- FÅ //api.github.com/users?page=1&per_page=10 Accept-kodning: gzip Brugeragent: 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 -Kodning: gzip '-H' Brugeragent: 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 Overførsel-kodning: klumpet Server: GitHub.com Adgangskontrol-Tillad-oprindelse: * ... Link:; rel = "næste",; rel = "første" X-GitHub-Request-Id: 8D6A: 1B54F: 3377D97: 3E37B36: 5A08DC93 Content-Type: application / json; charset = utf-8 ...10. Konklusion
I denne vejledning har vi vist Google HTTP-klientbiblioteket til Java og dets mere nyttige funktioner. Deres Github indeholder flere oplysninger om det samt kildekoden til biblioteket.
Som altid er den fulde kildekode til denne vejledning tilgængelig på GitHub.
