http verbs

http-verbs

HTTP-VERBS는 비동기 HTTP 호출을위한 인터페이스를 제공하는 스칼라 라이브러리입니다.

HMRC 세금 플랫폼에서 다른 HTTP 서비스를 호출 할 수있는 몇 가지 일반적인 우려를 다음을 포함합니다.

• HTTP 운송
• 핵심 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 )입니다.

용법

이용 가능한 두 가지 HTTPClients가 있지만 HttpClient 및 관련 API는 더 이상 사용되지 않았습니다. 대신 uk.gov.hmrc.http.client.HttpClientV2 사용하십시오.

uk.gov.hmrc.http.client.httpclientv2

이 클라이언트는 원래 HttpClient 보다 더 많은 기능을 가지고 있으며 사용하기가 간단합니다.

발신자의 컨텍스트를 나타내고 HTTP 응답을 처리하기위한 HeaderCarrier HttpReads 합니다.

또한 :

• 스트리밍을 지원합니다
• 기본 play.api.libs.ws.WSRequest transform 하여 요청을보다 쉽게 ​​사용자 정의 할 수 있습니다.
• URL 만 java.net.URL 로 만 허용합니다. 제공된 URL 보간기를 사용할 수 있습니다.

예제는 여기와 여기에서 찾을 수 있습니다

uk.gov.hmrc.http.httpclient

이 클라이언트는 더 이상 사용되지 않았습니다. 다음과 같이 마이그레이션 할 수 있습니다.

httpClient. GET [ ResponseType ](url)

becomes

httpClientV2.get( url " $url " ).execute[ ResponseType ]

그리고

httpClient. POST [ ResponseType ](url, payload, headers)

becomes

httpClientV2.post( url " $url " ).withBody( Json .toJson(payload)).setHeader(headers).execute[ ResponseType ]

이전에 프록시를 구성하거나 사용자 에이전트를 변경하기 위해 여러 httpclients를 작성한 경우, 통화 당 httpclientv2 API로 모두 제어 할 수 있기 때문에 더 이상 필요하지 않습니다.

헤더 조작

HeaderCarrier 크게 발신자의 불변의 표현으로 취급되어야합니다. 요청으로 전송되는 헤더를 조작 해야하는 경우 HttpClientV2 API로이를 수행 할 수 있습니다.

예를 들어, 기본 사용자 에이전트 또는 HeaderCARIRIRE에 정의 된 인증 헤더를 무시하려면 기존 제품을 대체 할 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 사용하면 프록시를 사용하려면 WSProxy 에서 혼합하고 구성하기 위해 새 인스턴스의 httpclient를 생성해야합니다. HttpClientV2 사용하면 동일한 클라이언트를 사용하여 통화 당 withProxy 호출 할 수 있습니다. 예를 들어

httpClientV2.get( url " $url " ).withProxy.execute[ ResponseType ]

• http-verbs.proxy.enabled 로 활성화 된 WSProxyConfiguration.buildWsProxyServer 사용합니다. 기본적으로 비활성화되어 지역 개발 및 테스트에 적합하지만 배포시 (환경 구성에 의해 활성화되지 않은 경우) 활성화해야합니다.

스트리밍

스트리밍은 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는 지원되는 최대를 초과하면 ( http-verbs.auditing.maxBodyLength )에 의해 구성된 최대를 초과하는 경우 감사 로그에 대한 페이로드를 자릅니다.

이는 HTTPClient로 너무 커서 거부 된 감사가 아마도 HTTPClientV2로 허용 될 것임을 의미합니다.

켈 감사 행동에 미칠 수있는 잠재적 영향을 확인하십시오.

URL 보간기

쿼리 및 경로 매개 변수를 올바르게 탈출하는 데 도움이되는 URL 보간기가 제공되었습니다.

 import uk . gov . hmrc . http . StringContextOps

url " http://localhost:8080/users/ ${user.id} ?email= ${user.email} "

헤더

HeaderCarrier 생성

요청을 사용할 수 있으면 HeaderCarrierConverter 로 HeaderCarrier 작성해야합니다.이를 통해 적절한 헤더가 내부 호스트로 전달되도록합니다.

예 : 뒷면 :

 HeaderCarrierConverter .fromRequest(request)

그리고 프론트 엔드 :

 HeaderCarrierConverter .fromRequestAndSession(request, request.session)

프론트 엔드 엔드 포인트가 API 호출을 서비스하는 경우 fromRequestAndSession 세션에서 권한 부여 토큰 만 찾아야하며 요청 헤더로 제공되는 모든 것을 무시하기 때문에 fromRequest 사용해야합니다.

요청이없는 경우 비동기 호출의 경우 기본 매개 변수로 새로운 헤드 커리어를 만들 수 있습니다.

 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 조작해야합니다.

client. GET ( " https://internalhost/api " )(hc.copy(authorization = Some ( Authorization ( " Basic 1234 " ))))

실조 화 반응

응답은 httpreads 인스턴스에 의해 실조화됩니다.

자신의 인스턴스를 만들거나 제공된 인스턴스를 다음과 함께 사용할 수 있습니다.

 import uk . gov . hmrc . http . HttpReads . Implicits . _

기본적으로 (명시 적 수입없이)가 더 이상 사용되지 않았습니다. 자세한 내용은 여기를 참조하십시오.

HttpReads 상태 코드 및 응답 본문을 사용하여 HttpResponse 를 모델로 변환하는 방법을 설명합니다.

위의 가져 오기와의 범위로 가져온 제공된 인스턴스는 다음을 허용합니다.

• RAW httpresponse 요청 :

  client. GET [ HttpResponse ](url)

• Play를 사용하여 JSON에서 응답 본문을 변환합니다. JSON은 다음을 읽습니다.

   implicit val reads : Reads [ MyModel ] = ???
  client.get[ MyModel ](url)

  참고이 인스턴스는 비 Success 상태 코드에 대한 UpstreamErrorResponse 사용하여 실패한 선물을 반환합니다. JsValidationException 이 예외는 필요한 경우 복구 될 수 있으므로 JSON 구문 분석 실패가 유사하게 반환됩니다.
• 404를 처리하지 None

  implict val reads : Reads [ MyModel ] = ???
  client.get[ Option [ MyModel ]](url)

• 비 서식 상태 코드를 UpstreamErrorResponse Either 반환하십시오

  implict val reads : Reads [ MyModel ] = ???
  client.get[ Either [ UpstreamErrorResponse , MyModel ]](url)

테스트

SBT 빌드에서 테스트 종속성에 다음을 추가하십시오.

libraryDependencies + = " uk.gov.hmrc " %% " http-verbs-test-play-xx " % " x.x.x " % Test

Wiremock은 요청 및 응답 모두에 대한 URL, 헤더 및 바디 필드에 대한 광범위한 주장과 함께 HTTP-Verbs 코드를 테스트하는 데 사용되는 것이 좋습니다. 이것은 대부분의 것을 테스트하고 "소유하지 않는 것을 조롱하는 것"과 관련이 없으며이 라이브러리의 변경 사항이 잡히도록합니다. 즉,이 라이브러리를 사용한 결과는 도서관이 예상대로 호출 된 경우가 아니라 의도 된 것입니다.

WireMockSupport Trait은 테스트를위한 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 라이센스에 따라 라이센스가 부여 된 오픈 소스 소프트웨어입니다.