Google-Http-Clientのガイド
1. 概要
この記事では、Google HTTP Client Library for Javaについて説明します。これは、HTTP接続プロトコルを介してリソースにアクセスするための、高速で抽象化されたライブラリです。
クライアントの主な機能は次のとおりです。
-
低レベルのライブラリを分離できるHTTP抽象化レイヤー
-
HTTP応答および要求コンテンツの高速で効率的かつ柔軟なJSONおよびXML解析モデル
-
HTTPリソースマッピングの使いやすい注釈と抽象化
このライブラリーはJava 5以降でも使用できるため、レガシー(SEおよびEE)プロジェクトのかなりの選択肢となります。
この記事では、ライブラリの最も興味深い機能のいくつかをカバーしながら、will connect to the GitHub API and retrieve usersという単純なアプリケーションを開発します。
2. Mavenの依存関係
ライブラリを使用するには、google-http-clientの依存関係が必要です。
com.google.http-client
google-http-client
1.23.0
最新バージョンはMaven Centralにあります。
3. 簡単なリクエストを行う
まず、GitHubページに簡単なGETリクエストを送信して、GoogleHttpクライアントが箱から出してどのように機能するかを紹介しましょう。
HttpRequestFactory requestFactory
= new NetHttpTransport().createRequestFactory();
HttpRequest request = requestFactory.buildGetRequest(
new GenericUrl("https://github.com"));
String rawResponse = request.execute().parseAsString()
最も簡単なリクエストを行うには、少なくとも次のものが必要です。
-
HttpRequestFactoryこれはリクエストの作成に使用されます
-
HttpTransport低レベルHTTPトランスポート層の抽象化
-
GenericUrlはURLをラップするクラスです
-
HttpRequestは、リクエストの実際の実行を処理します
次のセクションでは、これらすべてと、JSON形式を返す実際のAPIを使用したより複雑な例について説明します。
4. プラグ可能なHTTPトランスポート
ライブラリには、十分に抽象化されたHttpTransportクラスがあり、ライブラリとchange to the underlying low-level HTTP transport library of choiceの上に構築できます。
public class GitHubExample {
static HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
}
この例では、すべてのJava SDKにあるHttpURLConnectionに基づくNetHttpTransportを使用しています。 これはよく知られていて信頼できるので、最初の選択として適しています。
もちろん、高度なカスタマイズが必要な場合があります。そのため、より複雑な低レベルライブラリが必要になります。
この種の場合、ApacheHttpTransport:があります
public class GitHubExample {
static HttpTransport HTTP_TRANSPORT = new ApacheHttpTransport();
}
ApacheHttpTransportは、接続を構成するためのさまざまな選択肢を含む一般的なApache HttpClientに基づいています。
さらに、ライブラリには低レベルの実装を構築するオプションがあり、非常に柔軟になっています。
5. JSON解析
Google Httpクライアントには、JSON解析用の別の抽象化が含まれています。 これの主な利点は、the choice of low-level parsing library is interchangeableです。
3つの組み込みの選択肢があり、そのすべてがJsonFactory,を拡張し、独自の選択肢も含まれています。
5.1. 交換可能な解析ライブラリ
この例では、google-http-client-jackson2の依存関係を必要とするJackson2実装を使用します。
com.google.http-client
google-http-client-jackson2
1.23.0
これに続いて、JsonFactory:を含めることができます
public class GitHubExample {
static HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
staticJsonFactory JSON_FACTORY = new JacksonFactory();
}
JacksonFactoryは、解析/シリアル化操作用の最も高速で最も人気のあるライブラリです。
これには、ライブラリのサイズが犠牲になります(特定の状況では問題になる可能性があります)。 このため、GoogleはGsonFactoryも提供しています。これは、軽量のJSON解析ライブラリであるGoogleGSONライブラリの実装です。
また、低レベルのパーサー実装を作成する可能性もあります。
5.2. @Keyアノテーション
@Keyアノテーションを使用して、JSONから解析またはJSONにシリアル化する必要があるフィールドを示すことができます。
public class User {
@Key
private String login;
@Key
private long id;
@Key("email")
private String email;
// standard getters and setters
}
ここでは、Userの抽象化を行っています。これは、GitHub APIからバッチで受け取ります(実際の解析については、この記事の後半で説明します).
fields that don’t have the @Key annotation are considered internal and are not parsed from or serialized to JSONに注意してください。 また、フィールドの可視性は重要ではなく、ゲッターメソッドまたはセッターメソッドの存在も重要ではありません。
@Keyアノテーションの値を指定して、正しいJSONキーにマップできます。
5.3. GenericJson
宣言し、@Keyとしてマークしたフィールドのみが解析されます。
他のコンテンツを保持するために、GenericJson:を拡張するようにクラスを宣言できます。
public class User extends GenericJson {
//...
}
GenericJsonはMapインターフェースを実装します。つまり、getメソッドとputメソッドを使用して、要求/応答でJSONコンテンツを設定/取得できます。
6. 電話をかける
Google Httpクライアントでエンドポイントに接続するには、HttpRequestFactoryが必要です。これは、以前の抽象化HttpTransportと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));
});
}
}
次に必要になるのは、接続するURLです。 ライブラリはこれをGenericUrlを拡張するクラスとして処理し、宣言されたフィールドはクエリパラメータとして扱われます。
public class GitHubUrl extends GenericUrl {
public GitHubUrl(String encodedUrl) {
super(encodedUrl);
}
@Key
public int per_page;
}
ここで、GitHubUrl,で、per_pageプロパティを宣言して、GitHubAPIへの1回の呼び出しで必要なユーザー数を示します。
GitHubUrl:を使用して呼び出しを作成し続けましょう
private static void run() throws Exception {
HttpRequestFactory requestFactory
= HTTP_TRANSPORT.createRequestFactory(
(HttpRequest request) -> {
request.setParser(new JsonObjectParser(JSON_FACTORY));
});
GitHubUrl url = new GitHubUrl("https://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);
}
API呼び出しに必要なユーザー数を指定し、HttpRequestFactoryを使用してリクエストを作成する方法に注目してください。
これに続いて、GitHub APIの応答にはユーザーのリストが含まれているため、List<User>である複雑なTypeを提供する必要があります。
次に、最後の行で、呼び出しを行い、Userクラスのリストに対する応答を解析します。
7. カスタムヘッダー
APIリクエストを行うときに通常行うことの1つは、何らかのカスタムヘッダーまたは変更されたヘッダーを含めることです。
HttpHeaders headers = request.getHeaders();
headers.setUserAgent("example Client");
headers.set("Time-Zone", "Europe/Amsterdam");
これを行うには、リクエストを作成した後、実行して必要な値を追加する前に、HttpHeadersを取得します。
たとえば、Google Http Clientincludes some headers as special methods.User-Agentヘッダーを、setメソッドだけで含めようとすると、エラーがスローされることに注意してください。
8. 指数バックオフ
Google Httpクライアントのもう1つの重要な機能は、特定のステータスコードとしきい値に基づいてリクエストを再試行できることです。
リクエストオブジェクトを作成した直後に、指数バックオフ設定を含めることができます。
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なので、HttpUnsuccessfulResponseHandlerのインスタンスをHttpRequestに含めてアクティブ化する必要があります。
9. ロギング
Google Httpクライアントはjava.util.logging.Loggerを使用して、URL、ヘッダー、コンテンツなどのHTTP要求と応答の詳細をログに記録します。
通常、ロギングはlogging.propertiesファイルを使用して管理されます。
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = ALL
com.google.api.client.http.level = ALL
この例ではConsoleHandlerを使用していますが、FileHandlerを選択することもできます。
プロパティファイルは、JDKロギング機能の動作を設定します。 この設定ファイルには、システムプロパティとして指定することができます。
-Djava.util.logging.config.file=logging.properties
そのため、ファイルとシステムプロパティを設定すると、ライブラリは次のようなログを生成します。
-------------- REQUEST --------------
GET https://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)' -- 'https://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. 結論
このチュートリアルでは、Java用のGoogleHTTPクライアントライブラリとそのより便利な機能を紹介しました。 それらのGithubには、ライブラリのソースコードだけでなく、それに関する詳細情報が含まれています。
いつものように、このチュートリアルの完全なソースコードはover on GitHubで入手できます。