適用於 Java 的 Azure SDK 疑難解答概觀

發行項
12/13/2023

本文介紹使用適用於 Java 的 Azure SDK 時可供您使用的許多疑難解答工具，以及提供進一步詳細數據的其他文章連結。

適用於 Java 的 Azure SDK 是由許多用戶端連結庫所組成，每個存在的 Azure 服務都有一或多個。我們可確保所有客戶端連結庫都建置為一致、高標準，並具有設定、記錄、例外狀況處理和疑難解答的常見模式。如需詳細資訊，請參閱使用適用於 Java 的 Azure SDK。

因為疑難解答可以跨越如此廣泛的主題領域，所以我們開發了下列您可能想要檢閱的疑難解答指南：

針對 Azure 身分識別驗證問題進行疑難解答，包括驗證失敗調查技術、Azure 身分識別 Java 用戶端連結庫中認證類型的常見錯誤，以及解決這些錯誤的風險降低步驟。
針對相依性版本衝突進行疑難解答涵蓋與診斷、緩和和最小化相依性衝突相關的主題。當您在以 Maven 和 Gradle 等工具建置的系統中，使用適用於 Java 的 Azure SDK 用戶端連結庫時，可能會發生這些衝突。
針對網路問題進行疑難解答，涵蓋使用 Fiddler 和 Wireshark 等工具，與客戶端連結庫外部 HTTP 偵錯相關的主題。

除了這些一般疑難解答指南之外，我們也提供連結庫特定的疑難解答指南。現在有下列指南可供使用：

除了這些檔之外，下列內容提供在與適用於 Java 的 Azure SDK 相關時，充分利用記錄和例外狀況處理的指引。

在適用於 Java 的 Azure SDK 中使用記錄

下列各節說明如何啟用不同類型的記錄。

啟用客戶端記錄

若要針對問題進行疑難解答，請務必先啟用記錄來監視應用程式的行為。記錄中的錯誤和警告通常會提供錯誤狀況的實用見解，有時包括修正問題的更正動作。 Azure SDK for Java 具有完整的記錄支援。如需詳細資訊，請參閱在 Azure SDK for Java 中設定記錄。

啟用 HTTP 要求/回應記錄

針對問題進行疑難解答時，檢閱 HTTP 要求在 Azure 服務之間傳送和接收時很有用。若要啟用記錄 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`	記錄 HEADERS 和 BODY 中的所有內容。

注意

當您記錄要求和響應主體時，請確定它們不包含機密資訊。當您記錄查詢參數和標頭時，客戶端連結庫有一組預設的查詢參數和標頭，這些參數和標頭視為可安全記錄。您可以新增其他安全記錄的查詢參數和標頭，如下列範例所示：

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

適用於 Java 的 Azure SDK 中的例外狀況處理

大部分的適用於 Java 的 Azure SDK 用戶端服務方法都會在失敗時擲回 HttpResponseException 或更特定的子類別。此 HttpResponseException 類型包含詳細的回應錯誤物件，可提供對發生錯誤情況的特定實用見解，並包含修正常見問題的更正動作。您可以在物件的 message 屬性 HttpResponseException 內找到此錯誤資訊。因為這些例外狀況是運行時間例外狀況，因此 JavaDoc 參考檔不會明確加以呼叫。

下列範例示範如何使用同步客戶端攔截此例外狀況：

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
}

使用異步用戶端時，您可以攔截並處理錯誤回呼中的例外狀況，如下列範例所示：

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 是熱門的開放原始碼可觀察性架構，可用於產生、擷取及收集雲端原生軟體的遙測數據。

如需如何在 Azure SDK for Java 中啟用追蹤的詳細資訊，請參閱在 Azure SDK for Java 中設定追蹤。

下一步

如果本文中的疑難解答指引無法協助您在使用適用於 Java 的 Azure SDK 用戶端連結庫時解決問題，建議您在適用於 Java 的 Azure SDK GitHub 存放庫中提出問題。

共用方式為