共用方式為

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

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

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

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

除了這些一般疑難解答指南外，我們還提供針對書庫的疑難解答指南。 現在有下列指南可供使用：

除了這些文件之外，下列內容提供有關在使用適用於 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 存放庫中 提出問題，。

  • Last updated on