Java용 Azure SDK에 대한 문제 해결 개요

아티클
10/23/2023

이 문서에서는 Java용 Azure SDK를 사용할 때 사용할 수 있는 많은 문제 해결 도구와 추가 세부 정보가 포함된 다른 문서에 대한 링크를 소개합니다.

Java용 Azure SDK는 존재하는 각 Azure 서비스에 대해 하나 이상의 클라이언트 라이브러리로 구성됩니다. 모든 클라이언트 라이브러리가 구성, 로깅, 예외 처리 및 문제 해결에 대한 일반적인 패턴을 사용하여 일관되고 높은 표준으로 빌드되도록 합니다. 자세한 내용은 Java용 Azure SDK 사용을 참조 하세요.

문제 해결은 광범위한 주제 영역에 걸쳐 있을 수 있으므로 검토할 수 있는 다음 문제 해결 가이드를 개발했습니다.

Azure ID 인증 문제 해결에는 인증 실패 조사 기술, Azure Identity Java 클라이언트 라이브러리의 자격 증명 유형에 대한 일반적인 오류 및 이러한 오류를 해결하기 위한 완화 단계가 포함되어 있습니다.
종속성 버전 충돌 문제 해결은 종속성 충돌 진단, 완화 및 최소화와 관련된 주제를 다룹니다. 이러한 충돌은 Maven 및 Gradle과 같은 도구를 사용하여 빌드된 시스템에서 Java용 Azure SDK 클라이언트 라이브러리를 사용할 때 발생할 수 있습니다.
Fiddler 및 Wireshark와 같은 도구를 사용하여 클라이언트 라이브러리 외부의 HTTP 디버깅과 관련된 주제를 다루는 네트워킹 문제를 해결 합니다.

이러한 일반적인 문제 해결 가이드와 함께 라이브러리별 문제 해결 가이드도 제공합니다. 현재 다음 가이드를 사용할 수 있습니다.

이러한 문서 외에도 다음 콘텐츠는 Java용 Azure SDK와 관련된 로깅 및 예외 처리를 최대한 활용하는 방법에 대한 지침을 제공합니다.

Java용 Azure SDK에서 로깅 사용

다음 섹션에서는 다양한 종류의 로깅을 사용하도록 설정하는 방법을 설명합니다.

클라이언트 로깅 사용

문제를 해결하려면 먼저 로깅을 사용하도록 설정하여 애플리케이션의 동작을 모니터링하는 것이 중요합니다. 로그의 오류 및 경고는 일반적으로 무엇이 잘못되었는지에 대한 유용한 인사이트를 제공하고 때로는 문제를 해결하기 위한 수정 작업을 포함합니다. Java용 Azure SDK에는 포괄적인 로깅 지원이 있습니다. 자세한 내용은 Java용 Azure SDK의 로깅 구성을 참조하세요.

HTTP 요청/응답 로깅 사용

문제를 해결할 때 Azure 서비스 간에 전송 및 수신되는 HTTP 요청을 검토하는 것이 유용합니다. HTTP 요청 및 응답 페이로드 로깅을 사용하도록 설정하려면 다음 예제와 같이 클라이언트 작성기에서 거의 모든 Java 클라이언트 라이브러리용 Azure SDK를 구성할 수 있습니다. 특히 클라이언트 작성기에서 httpLogOptions 메서드 및 에서 사용할 수 있는 HttpLogDetailLevel열거형 값에 특히 주의해야 합니다.

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .connectionString(connectionString)
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();

이 코드는 단일 클라이언트 인스턴스에 대한 HTTP 요청/응답 로깅을 변경합니다. 또는 환경 변수를 다음 표의 값 중 하나로 설정 AZURE_HTTP_LOG_DETAIL_LEVEL 하여 전체 애플리케이션에 대한 로깅 HTTP 요청 및 응답을 구성할 수 있습니다. 이 변경은 HTTP 요청/응답 로깅을 지원하는 모든 Azure 클라이언트에 대한 로깅을 사용하도록 설정하는 것이 중요합니다.

값	로깅 수준
`none`	HTTP 요청/응답 로깅을 사용할 수 없습니다.
`basic`	URL, HTTP 메서드 및 요청을 완료하는 시간만 기록합니다.
`headers`	BASIC의 모든 항목과 모든 요청 및 응답 헤더를 기록합니다.
`body`	BASIC의 모든 항목과 모든 요청 및 응답 본문을 기록합니다.
`body_and_headers`	헤더 및 본문에 모든 항목을 기록합니다.

참고 항목

요청 및 응답 본문을 기록할 때 기밀 정보가 포함되어 있지 않은지 확인합니다. 쿼리 매개 변수 및 헤더를 기록할 때 클라이언트 라이브러리에는 기록해도 안전한 것으로 간주되는 기본 쿼리 매개 변수 및 헤더 집합이 있습니다. 다음 예제와 같이 기록해도 안전한 추가 쿼리 매개 변수 및 헤더를 추가할 수 있습니다.

clientBuilder.httpLogOptions(new HttpLogOptions()
    .addAllowedHeaderName("safe-to-log-header-name")
    .addAllowedQueryParamName("safe-to-log-query-parameter-name"))

Java용 Azure SDK의 예외 처리

대부분의 Java용 Azure SDK 클라이언트 서비스 메서드는 실패 시 HttpResponseException 또는 보다 구체적인 하위 클래스를 throw합니다. 이 형식에는 HttpResponseException 무엇이 잘못되었는지에 대한 구체적인 유용한 인사이트를 제공하고 일반적인 문제를 해결하기 위한 수정 작업을 포함하는 자세한 응답 오류 개체가 포함되어 있습니다. 개체의 HttpResponseException 메시지 속성 내에서 이 오류 정보를 찾을 수 있습니다. 이러한 예외는 런타임 예외이므로 JavaDoc 참조 설명서에서 명시적으로 호출하지 않습니다.

다음 예제에서는 동기 클라이언트를 사용하여 이 예외를 catch하는 방법을 보여줍니다.

try {
    ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
    client.getConfigurationSetting(setting);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
    // Do something with the exception
}

비동기 클라이언트를 사용하면 다음 예제와 같이 오류 콜백에서 예외를 catch하고 처리할 수 있습니다.

ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
asyncClient.getConfigurationSetting(setting)
    .doOnSuccess(ignored -> System.out.println("Success!"))
    .doOnError(
        error -> error instanceof ResourceNotFoundException,
        error -> System.out.println("Exception: 'getConfigurationSetting' could not be performed."));

Java용 Azure SDK에서 추적 사용

Java용 Azure SDK는 포괄적인 추적 지원을 제공하므로 애플리케이션 코드 및 사용 중인 클라이언트 라이브러리를 통해 실행 흐름을 볼 수 있습니다. OpenTelemetry SDK를 사용하고 구성 하거나 OpenTelemetry 호환 에이전트를 사용하여 Azure 클라이언트 라이브러리에서 추적을 사용하도록 설정할 수 있습니다. OpenTelemetry는 클라우드 네이티브 소프트웨어에 대한 원격 분석 데이터를 생성, 캡처 및 수집하기 위한 인기 있는 오픈 소스 관찰 프레임워크입니다.

Java용 Azure SDK에서 추적을 사용하도록 설정하는 방법에 대한 자세한 내용은 Java용 Azure SDK에서 추적 구성을 참조하세요.

다음 단계

이 문서의 문제 해결 지침이 Java용 Azure SDK 클라이언트 라이브러리를 사용할 때 문제를 해결하는 데 도움이 되지 않는 경우 Java GitHub 리포지토리용 Azure SDK에 문제를 제출하는 것이 좋습니다.

다음을 통해 공유