http verbs
15.1.0
HTTP-Verbsは、非同期HTTP呼び出しを行うためのインターフェイスを提供するSCALAライブラリです。
以下を含む、HMRC税プラットフォームで他のHTTPサービスを呼び出すためのいくつかの一般的な懸念をカプセル化します。
変更と移行については、Changelogを参照してください。
SBTビルドで追加：
resolvers + = MavenRepository ( " HMRC-open-artefacts-maven2 " , " https://open.artefacts.tax.service.gov.uk/maven2 " )
libraryDependencies + = " uk.gov.hmrc " %% " http-verbs-play-xx " % " x.x.x "ここで、 play-xxはあなたのバージョンのPlay（例えばplay-30 ）です。
利用可能な2つのHTTPCLIENTSがありますが、 HttpClientおよび関連するAPIは非推奨されています。代わりに、 uk.gov.hmrc.http.client.HttpClientV2を使用してください。
このクライアントは、元のHttpClientよりも多くの機能を備えており、使用が簡単です。
Callerのコンテキストを表すにはHeaderCarrierと、HTTP応答を処理するHttpReadsが必要です。
それも：
play.api.libs.ws.WSRequestをtransformて公開し、リクエストのカスタマイズを簡単にします。java.net.URLとしてのみ受け入れます。提供されたURLインタープロレーターを利用できます。例はこちらとこちらをご覧ください
このクライアントは非推奨です。次のように移行できます。
httpClient. GET [ ResponseType ](url)なります
httpClientV2.get( url " $url " ).execute[ ResponseType ]そして
httpClient. POST [ ResponseType ](url, payload, headers)なります
httpClientV2.post( url " $url " ).withBody( Json .toJson(payload)).setHeader(headers).execute[ ResponseType ]以前に複数のHTTPCLIENTSを作成してプロキシを構成したり、ユーザーエージェントを変更したりしていた場合、これらはすべて呼び出しごとにHTTPCLIENTV2 APIで制御できるため、これは必要ありません。
HeaderCarrier 、主に発信者の不変の表現として扱われるべきです。リクエストで送信されるヘッダーを操作する必要がある場合は、 HttpClientV2 APIでこれを行うことができます。
たとえば、デフォルトのユーザーエージェントまたはheadercarrierで定義されている承認ヘッダーをオーバーライドするには、既存のものを置き換えるsetHeaderを使用できます。
httpClientV2.get( url " $url " )
.setHeader( " User-Agent " - > userAgent)
.setHeader( " Authorization " - > authorization)
.execute[ ResponseType ]デフォルトのヘッダーに追加する場合は、 transformを使用して基礎となるWSClientのaddHttpHeadersにアクセスできます。例えば
httpClientV2.get( url " $url " )
.transform(_.addHttpHeaders( " User-Agent " - > userAgent))
.execute[ ResponseType ] "Content-Type"をWSRequestで設定したら変更できないことに注意してください。そのため、暗黙のBodyWriterによって定義されたものと別のものを必要とする場合は、ボディを提供する前に設定する必要があります。例えば
httpClientV2.post( url " $url " )
.setHeader( " Content-Type " - > " application/xml " )
.withBody(< foo >bar</ foo >)HttpClientを使用すると、プロキシを使用するには、httpClientの新しいインスタンスを作成してWSProxyと構成を混合する必要があります。 HttpClientV2では、同じクライアントで実行でき、コールごとにwithProxyを呼び出します。例えば
httpClientV2.get( url " $url " ).withProxy.execute[ ResponseType ]WSProxyConfiguration.buildWsProxyServer http-verbs.proxy.enabled使用します。現地の開発やテストに適したデフォルトでは無効になっていますが、展開時に有効にする必要があります（環境構成によってまだ有効になっていない場合）。 ストリーミングはHttpClientV2でサポートされており、非ストリーミングコールと同じように監査されます。ペイロードは、サポートされている最大値を超える場合、監査ログで切り捨てられることに注意してください（ http-verbs.auditing.maxBodyLength ）。
ストリーミングされたリクエストは、単にwithBodyに渡すことができます。
val reqStream : Source [ ByteString , _] = ???
httpClientV2.post( url " $url " ).withBody(reqStream).execute[ ResponseType ]ストリーミングされた応答の場合、 executeのではなく、 streamを使用します。
httpClientV2.get( url " $url " ).stream[ Source [ ByteString , _]]HTTPCLIENTV2は、サポートされているMAXを超えた場合、監査ログのペイロードを切り捨てます（ http-verbs.auditing.maxBodyLengthによって構成されています）。
これは、HTTPCLIENTで大きすぎると拒否された監査がHTTPCLIENTV2で受け入れられることを意味します。
クエリとパスのパラメーターを正しく逃れるのに役立つURLインタープロレーターが提供されています。
import uk . gov . hmrc . http . StringContextOps
url " http://localhost:8080/users/ ${user.id} ?email= ${user.email} "HeaderCarrier 、リクエストが利用可能なときにHeaderCarrierConverterで作成する必要があります。これにより、適切なヘッダーが内部ホストに転送されるようになります。
例：バックエンドの場合：
HeaderCarrierConverter .fromRequest(request)フロントエンドの場合：
HeaderCarrierConverter .fromRequestAndSession(request, request.session) Frontend EndpointがAPI呼び出しのサービスを提供している場合、 fromRequestAndSessionセッションでの認証トークンのみを探し、リクエストヘッダーとして提供されているものを無視するため、おそらくfromRequestから使用する必要があります。
リクエストが利用できない非同期呼び出しの場合、デフォルトのパラメージで新しいheadercarrierを作成できます。
HeaderCarrier ()ヘッダーは、内部または外部であるかどうかに応じて、ホストに異なる方法で転送されます。この区別は、InternalServiceHostpatterns構成によって行われます。
外部ホストの場合、ユーザーエージェントヘッダーのみが送信されます。他のヘッダーは、動詞関数（ get 、 postなど）に明示的に提供する必要があります。
httpClientV2
.get( url " https://externalhost/api " )(hc)
.setHeader( " Authorization " - > " Bearer token " ) // explicit Authorization header for external request ユーザーエージェントに加えて、 HeaderCarrierで明示的にモデル化されたすべてのヘッダーは、内部ホストに転送されます。また、 bootstrap.http.headersAllowlist構成にリストされている場合、 HeaderCarrierの他のヘッダーを転送します。
これらの暗黙的に転送されたヘッダーのいずれかを交換したり、 setHeader関数に提供して他のヘッダーを追加したりできます。
注、元のHttpClientについては、動詞関数に提供されるヘッダーがHeadercarrierのものに加えて送信されるため、それを交換する場合は、 HeaderCarrierを操作する必要があります。
client. GET ( " https://internalhost/api " )(hc.copy(authorization = Some ( Authorization ( " Basic 1234 " ))))この応答は、HTTPREADSのインスタンスによって攻撃されます。
独自のインスタンスを作成するか、提供されたインスタンスを使用することができます
import uk . gov . hmrc . http . HttpReads . Implicits . _デフォルトのインクリティ（明示的なインポートなし）が非推奨されています。詳細については、こちらをご覧ください。
HttpReads 、ステータスコードと応答本体を使用してHttpResponseをモデルに変換する方法について説明します。
上記のインポートとともに範囲に導入された提供されたインスタンスは、次のことを可能にします。
client. GET [ HttpResponse ](url) implicit val reads : Reads [ MyModel ] = ???
client.get[ MyModel ](url)UpstreamErrorResponseで失敗した先物を返します。 jSONの解析障害は、 JsValidationExceptionが必要に応じて回復できるため、同様に返されます。Noneで404を処理しますimplict val reads : Reads [ MyModel ] = ???
client.get[ Option [ MyModel ]](url)Either上流のステータスコードをUpstreamErrorResponseとして返しますimplict val reads : Reads [ MyModel ] = ???
client.get[ Either [ UpstreamErrorResponse , MyModel ]](url)SBTビルドでは、テスト依存関係に以下を追加します。
libraryDependencies + = " uk.gov.hmrc " %% " http-verbs-test-play-xx " % " x.x.x " % TestWiremockは、リクエストと応答の両方について、URL、ヘッダー、およびボディフィールドに関する広範なアサーションを使用して、HTTP-Verbsコードのテストに使用することをお勧めします。これはほとんどのことをテストし、「あなたが所有していないものをock笑する」ことは含まれず、このライブラリの変更がキャッチされることを保証します。つまり、このライブラリを使用した結果は、図書館が予想どおりに呼び出された場合ではなく、意図されていたものです。
WireMockSupport特性は、テスト用にWiremockをセットアップするのに役立ちます。 wireMockHost 、 wireMockPort 、 wireMockUrlを提供します。これは、クライアントを適切に構成するために使用できます。
例：アプリケーション：
class MyConnectorSpec extends WireMockSupport with GuiceOneAppPerSuite {
override def fakeApplication () : Application =
new GuiceApplicationBuilder ()
.configure(
" connector.host " - > wireMockHost,
" connector.port " - > wireMockPort
).build()
private val connector = app.injector.instanceOf[ MyConnector ]
} HttpClientV2Support特性は、アプリケーションのインスタンス化に代わるものとしてHttpClientV2のインスタンスを提供できます。
class MyConnectorSpec extends WireMockSupport with HttpClientV2Support {
private val connector = new MyConnector (
httpClientV2,
Configuration ( " connector.url " - > wireMockUrl)
)
} ExternalWireMockSupport特性は、ヘッダー転送ルールの外部ホストとして扱われるホスト名のlocalhostの代わりに127.0.0.1使用するWireMockSupportの代替品です。これは、プラットフォームの外部のエンドポイントを呼び出すコネクタのテストに使用する必要があります。可変externalWireMockHost （またはexternalWireMockUrl ）を使用して、構成のホスト名を提供する必要があります。
必要に応じて、 WireMockSupportとExternalWireMockSupport両方を統合テストに一緒に使用できます。
ResponseMatchers特性は、応答をテストするための有用なヘルパーを提供します。
このコードは、Apache 2.0ライセンスに基づいてライセンスされているオープンソースソフトウェアです。
