Java용 Azure SDK의 HTTP 클라이언트 및 파이프라인

아티클
10/23/2023

이 문서에서는 Java용 Azure SDK 내에서 HTTP 클라이언트 및 파이프라인 기능을 사용하는 방법에 대해 간략히 설명합니다. 이 기능은 Java 라이브러리용 모든 Azure SDK를 사용하는 개발자에게 일관되고 강력하며 유연한 환경을 제공합니다.

HTTP 클라이언트

Java용 Azure SDK는 추상화로 HttpClient 구현됩니다. 이 추상화를 통해 여러 HTTP 클라이언트 라이브러리 또는 사용자 지정 구현을 허용하는 플러그형 아키텍처를 사용할 수 있습니다. 그러나 대부분의 사용자에 대한 종속성 관리를 간소화하기 위해 모든 Azure 클라이언트 라이브러리는 azure-core-http-netty에 종속됩니다. 따라서 Netty HTTP 클라이언트는 Java 라이브러리용 모든 Azure SDK에서 사용되는 기본 클라이언트입니다.

Netty가 기본 HTTP 클라이언트이지만, SDK는 프로젝트에 이미 있는 종속성에 따라 세 개의 클라이언트 구현을 제공합니다. 이러한 구현은 다음과 같습니다.

참고 항목

Java용 Azure SDK와 함께 JDK HttpClient 는 JDK 12 이상에서만 지원됩니다.

기본 HTTP 클라이언트 바꾸기

다른 구현을 선호하는 경우 빌드 구성 파일에서 제외하여 Netty에 대한 종속성을 제거할 수 있습니다. Maven pom.xml 파일에서 Netty 종속성을 제외하고 다른 종속성을 포함합니다.

다음 예제에서는 라이브러리에 대한 실제 종속성에서 Netty 종속성을 제외하는 azure-security-keyvault-secrets 방법을 보여줍니다. 다음과 같이 모든 적절한 com.azure 라이브러리에서 Netty를 제외해야 합니다.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-secrets</artifactId>
    <version>4.2.2.</version>
    <exclusions>
      <exclusion>
        <groupId>com.azure</groupId>
        <artifactId>azure-core-http-netty</artifactId>
      </exclusion>
    </exclusions>
</dependency>

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-okhttp</artifactId>
  <version>1.3.3</version>
</dependency>

참고 항목

Netty 종속성을 제거하지만 그 자리에 구현을 제공하지 않으면 애플리케이션이 시작되지 않습니다. 구현은 HttpClient 클래스 경로에 있어야 합니다.

HTTP 클라이언트 구성

서비스 클라이언트를 빌드할 때는 기본적으로 .를 사용합니다 HttpClient.createDefault(). 이 메서드는 제공된 HTTP 클라이언트 구현을 기반으로 기본 HttpClient 인스턴스를 반환합니다. 프록시와 같이 더 복잡한 HTTP 클라이언트가 필요한 경우 각 구현에서 구성된 HttpClient 인스턴스를 구성할 수 있는 작성기를 제공합니다. 작성기는 NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilder 및 JdkAsyncHttpClientBuilder입니다.

다음 예제에서는 Netty, OkHttp 및 JDK 11 HTTP 클라이언트를 사용하여 HttpClient 인스턴스를 빌드하는 방법을 보여 줍니다. 이러한 인스턴스는 암호 weakPassword를 사용하여 사용자 예제를 통해 http://localhost:3128 프록시하고 인증합니다.

// Netty
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

// OkHttp
HttpClient httpClient = new OkHttpAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

// JDK 11 HttpClient
HttpClient client = new JdkAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

이제 서비스와 통신하기 위해 클라이언트로 사용하기 위해 생성된 HttpClient 인스턴스를 서비스 클라이언트 작성기에 전달할 수 있습니다. 다음 예제에서는 새 HttpClient 인스턴스를 사용하여 Azure Storage Blob 클라이언트를 빌드합니다.

BlobClient blobClient = new BlobClientBuilder()
    .connectionString(<connection string>)
    .containerName("container")
    .blobName("blob")
    .httpClient(httpClient)
    .build();

관리 라이브러리의 경우 관리자 구성 중에 설정할 HttpClient 수 있습니다.

AzureResourceManager azureResourceManager = AzureResourceManager.configure()
    .withHttpClient(httpClient)
    .authenticate(credential, profile)
    .withDefaultSubscription();

HTTP 파이프라인

HTTP 파이프라인은 Azure용 Java 클라이언트 라이브러리에서 일관성 및 진단 가능성을 달성하는 주요 구성 요소 중 하나입니다. HTTP 파이프라인은 다음으로 구성됩니다.

HTTP 전송
HTTP 파이프라인 정책

클라이언트를 만들 때 사용자 지정 HTTP 파이프라인을 제공할 수 있습니다. 파이프라인을 제공하지 않으면 클라이언트 라이브러리는 특정 클라이언트 라이브러리와 작동하도록 구성된 파이프라인을 만듭니다.

HTTP 전송

HTTP 전송은 서버에 대한 연결을 설정하고 HTTP 메시지를 보내고 받는 역할을 합니다. HTTP 전송은 Azure SDK 클라이언트 라이브러리가 Azure 서비스와 상호 작용할 수 있도록 게이트웨이를 형성합니다. 이 문서의 앞부분에서 설명한 대로 Java용 Azure SDK는 기본적으로 Netty를 해당 HTTP 전송에 사용합니다. 그러나 SDK는 적절한 경우 다른 구현을 사용할 수 있도록 플러그형 HTTP 전송도 제공합니다. 또한 SDK는 OkHttp 및 JDK 11 이상과 함께 제공되는 HTTP 클라이언트에 대해 두 가지 HTTP 전송 구현을 추가로 제공합니다.

HTTP 파이프라인 정책

파이프라인은 각 HTTP 요청-응답 왕복에 대해 실행되는 일련의 단계로 구성됩니다. 각 정책에는 전용 목적이 있으며 요청 또는 응답 또는 경우에 따라 둘 다 작동합니다. 모든 클라이언트 라이브러리에는 표준 'Azure Core' 계층이 있으므로 이 계층은 각 정책이 파이프라인에서 순서대로 실행되도록 합니다. 요청을 보내면 정책이 파이프라인에 추가되는 순서대로 실행됩니다. 서비스에서 응답을 받으면 정책이 역순으로 실행됩니다. 파이프라인에 추가된 모든 정책은 요청을 보내기 전과 응답을 받은 후에 실행됩니다. 정책은 요청, 응답 또는 둘 다에 대해 작업할지 여부를 결정해야 합니다. 예를 들어 로깅 정책은 요청 및 응답을 기록하지만 인증 정책은 요청을 수정하는 데만 관심이 있습니다.

Azure Core 프레임워크는 정책을 실행하는 데 필요한 컨텍스트와 함께 필요한 요청 및 응답 데이터를 정책에 제공합니다. 그런 다음, 정책은 지정된 데이터로 작업을 수행하고 파이프라인의 다음 정책에 컨트롤을 전달할 수 있습니다.

HTTP pipeline diagram

HTTP 파이프라인 정책 위치

클라우드 서비스에 대한 HTTP 요청을 수행할 때 일시적인 오류를 처리하고 실패한 시도를 다시 시도하는 것이 중요합니다. 이 기능은 일반적인 요구 사항이므로 Azure Core는 일시적인 오류를 감시하고 요청을 자동으로 다시 시도할 수 있는 재시도 정책을 제공합니다.

따라서 이 재시도 정책은 전체 파이프라인을 재시도 정책 전에 실행되는 정책과 재시도 정책 후에 실행되는 정책의 두 부분으로 분할합니다. 재시도 정책 전에 추가된 정책은 API 작업당 한 번만 실행되며 재시도 정책 이후에 추가된 정책은 재시도 횟수만큼 실행됩니다.

따라서 HTTP 파이프라인을 빌드할 때 각 요청 재시도에 대한 정책을 실행할지 아니면 API 작업당 한 번 실행할지 이해해야 합니다.

일반적인 HTTP 파이프라인 정책

REST 기반 서비스에 대한 HTTP 파이프라인에는 인증, 재시도, 로깅, 원격 분석 및 헤더에 요청 ID 지정에 대한 정책이 포함된 구성이 있습니다. Azure Core는 파이프라인에 추가할 수 있는 이러한 일반적으로 필요한 HTTP 정책으로 미리 로드됩니다.

정책	GitHub 링크
재시도 정책	RetryPolicy.java
인증 정책	BearerTokenAuthenticationPolicy.java
로깅 정책	HttpLoggingPolicy.java
요청 ID 정책	RequestIdPolicy.java
원격 분석 정책	UserAgentPolicy.java

사용자 지정 HTTP 파이프라인 정책

HTTP 파이프라인 정책은 요청 및 응답을 수정하거나 데코레이팅하는 편리한 메커니즘을 제공합니다. 사용자 또는 클라이언트 라이브러리 개발자가 만든 파이프라인에 사용자 지정 정책을 추가할 수 있습니다. 파이프라인에 정책을 추가할 때 호출당 또는 재시도당 이 정책을 실행할지 여부를 지정할 수 있습니다.

사용자 지정 HTTP 파이프라인 정책을 만들려면 기본 정책 유형을 확장하고 몇 가지 추상 메서드를 구현하기만 하면 됩니다. 그런 다음, 정책을 파이프라인에 연결할 수 있습니다.

HTTP 요청의 사용자 지정 헤더

Java용 Azure SDK 클라이언트 라이브러리는 다음 예제와 같이 공용 API의 개체를 통해 Context 사용자 지정된 헤더를 정의하는 일관된 방법을 제공합니다.

// Add your headers
HttpHeaders headers = new HttpHeaders();
headers.set("my-header1", "my-header1-value");
headers.set("my-header2", "my-header2-value");
headers.set("my-header3", "my-header3-value");

// Call API by passing headers in Context.
configurationClient.addConfigurationSettingWithResponse(
    new ConfigurationSetting().setKey("key").setValue("value"),
    new Context(AddHeadersFromContextPolicy.AZURE_REQUEST_HTTP_HEADERS_KEY, headers));

// The three headers are now be added to the outgoing HTTP request.

자세한 내용은 AddHeadersFromContextPolicy 클래스를 참조 하세요.

기본 TLS/SSL 라이브러리

기본적으로 모든 클라이언트 라이브러리는 Tomcat 네이티브 보링 SSL 라이브러리를 사용하여 TLS/SSL 작업에 대한 기본 수준 성능을 사용하도록 설정합니다. 지루한 SSL 라이브러리는 Linux, macOS 및 Windows용 네이티브 라이브러리를 포함하는 uber JAR이며 JDK 내의 기본 TLS/SSL 구현에 비해 더 나은 성능을 제공합니다.

Tomcat-Native TLS/SSL 종속성 크기 줄이기

기본적으로 Tomcat-Native Boring SSL 라이브러리의 uber JAR은 Java용 Azure SDK에서 사용됩니다. 이 종속성의 크기를 줄이려면 다음 예제와 os 같이 netty-tcnative에 따라 분류자를 사용하여 종속성을 포함해야 합니다.

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative-boringssl-static</artifactId>
      <version>2.0.25.Final</version>
      <classifier>${os.detected.classifier}</classifier>
    </dependency>
    ...
  </dependencies>
  ...
  <build>
    ...
    <extensions>
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    ...
  </build>
  ...
</project>

JDK TLS/SSL 사용

Tomcat-Native Boring SSL 대신 기본 JDK TLS/SSL을 사용하려는 경우 Tomcat 네이티브 보링 SSL 라이브러리를 제외해야 합니다. 테스트에 따라 JDK TLS/SSL의 성능은 Tomcat-Native Boring SSL에 비해 30% 느립니다. 사용하거나 나중에 HttpClient사용하는 com.azure:azure-core:1.28.0 경우 -implementing 라이브러리(예: com.azure:azure-core-http-netty)는 Tomcat-Native Boring SSL에 대한 종속성을 관리합니다. 종속성을 제외하려면 POM 파일에 다음 구성을 추가합니다.

<project>
  ...
  <dependencies>
    ...
    <dependency>
     <groupId>com.azure</groupId>
       <artifactId>azure-core-http-netty</artifactId>
       <version>1.13.6</version>
       <exclusions>
         <exclusion>
           <groupId>io.netty</groupId>
           <artifactId>netty-tcnative-boringssl-static</artifactId>
         </exclusion>
       </exclusions>
    </dependency>
    ...
  </dependencies>
  ...
</project>

다음 단계

Java용 Azure SDK의 HTTP 클라이언트 기능에 익숙해졌으므로 사용 중인 HTTP 클라이언트를 추가로 사용자 지정하는 방법을 알아봅니다. 자세한 내용은 Java용 Azure SDK에서 프록시 구성을 참조하세요.