共用方式為

針對 Azure 事件中樞 進行疑難解答

  • 發行項

本文涵蓋失敗調查技術、事件中樞連結庫中認證類型的常見錯誤，以及解決這些錯誤的風險降低步驟。 除了適用於事件中樞使用案例的一般疑難解答技術和指引之外，下列文章還涵蓋事件中樞連結庫的特定功能：

本文的其餘部分涵蓋適用於事件中樞連結庫所有使用者的一般疑難解答技術和指引。

處理事件中樞例外狀況

所有事件中樞例外狀況都會包裝在 AmqpException中。 這些例外狀況通常會有一個基礎 AMQP 錯誤碼，指定是否應該重試錯誤。 針對可重試的錯誤（也就是 amqp:connection:forced 或 amqp:link:detach-forced），用戶端連結庫會根據具現化用戶端時指定的重試選項，嘗試從這些錯誤復原。 若要設定重試選項，請遵循範例 將事件發佈至特定分割區。 如果錯誤無法重試，則需要解決一些設定問題。

解決AMQP例外狀況所代表之特定例外狀況的建議方式，是遵循 事件中樞傳訊例外狀況 指引。

在例外狀況訊息中尋找相關信息

AmqpException 包含下列三個欄位，其中描述錯誤：

  • getErrorCondition：基礎 AMQP 錯誤。 如需錯誤的描述，請參閱 AmqpErrorCondition 列舉 檔或 OASIS AMQP 1.0 規格。
  • isTransient：值，指出是否可能嘗試執行相同的作業。 當錯誤為暫時性時，SDK 用戶端會套用重試原則。
  • getErrorContext：包含下列 AMQP 錯誤來源的相關信息：

常見的例外狀況

amqp：connection：forced 和 amqp：link：detach-forced

當事件中樞的連線閑置時，服務會在一段時間后中斷用戶端連線。 此問題不是問題，因為用戶端在要求服務作業時重新建立連線。 如需詳細資訊，請參閱 Azure 服務匯流排 中的AMQP錯誤。

權限問題

AmqpException具有AmqpErrorCondition的 amqp:unauthorized-access ，表示提供的認證不允許使用事件中樞執行動作（接收或傳送）。 若要解決此問題，請嘗試下列工作：

  • 請仔細檢查您是否有正確的 連接字串。 如需詳細資訊，請參閱取得事件中樞 連接字串。
  • 請確定您的共用存取簽章 （SAS） 令牌已正確產生。 如需詳細資訊，請參閱 使用共用存取簽章授權存取事件中樞資源。

如需其他可能的解決方案，請參閱 針對事件中樞的驗證和授權問題進行疑難解答。

連線能力問題

線上到服務時逾時

若要解決逾時問題，請嘗試下列工作：

TLS/SSL 交握失敗

使用攔截 Proxy 時，可能會發生此錯誤。 若要確認，建議您在裝載環境中使用已停用 Proxy 進行測試。

套接字耗盡錯誤

應用程式應該偏好將事件中樞用戶端視為單一實例，並在應用程式的存留期內建立和使用單一實例。 這項建議很重要，因為每個客戶端類型都會管理其連線。 當您建立新的事件中樞用戶端時，會產生使用套接字的新AMQP連線。 此外，客戶端必須繼承自 java.io.Closeable，因此您的應用程式必須負責在使用用戶端完成時呼叫 close() 。

若要在建立多個用戶端時使用相同的AMQP連線，您可以使用 EventHubClientBuilder.shareConnection() 旗標、保存該 EventHubClientBuilder的參考，以及從同一個產生器實例建立新的用戶端。

使用IoT連接字串 連線

因為翻譯 連接字串 需要查詢 IoT 中樞 服務，所以事件中樞用戶端連結庫無法直接使用它。 IoT 連線 ionString.java 範例說明如何查詢 IoT 中樞，將 IoT 連接字串 轉譯為可與事件中樞搭配使用的 IoT 連接字串。

如需詳細資訊，請參閱下列文章：

無法將元件新增至 連接字串

舊版事件中樞用戶端可讓客戶將元件新增至從 Azure 入口網站 擷取的 連接字串。 舊版用戶端位於套件 com.microsoft.azure：azure-eventhubs 和 com.microsoft.azure：azure-eventhubs-eph。 目前的世代僅支援 Azure 入口網站 所發行表單中的 連接字串。

新增 “TransportType=AmqpWebSockets”

若要使用 Web 套接字，請參閱 PublishEventsWithSocketsAndProxy.java 範例。

新增 “Authentication=Managed Identity”

若要使用受控識別進行驗證，請參閱 PublishEventsWithAzureIdentity.java 範例。

如需連結 Azure.Identity 庫的詳細資訊，請參閱我們的 驗證和 Azure SDK 部落格文章。

啟用和設定記錄

適用於 Java 的 Azure SDK 提供一致的記錄案例，可協助針對應用程式錯誤進行疑難解答，並協助加速解決。 產生的記錄會在到達終端狀態之前，先擷取應用程式流程來協助尋找根本問題。 如需記錄的指引，請參閱 在適用於 Java 的 Azure SDK 中設定記錄和 疑難解答概觀。

除了啟用記錄之外，將記錄層級設定為 VERBOSE 或 DEBUG 提供連結庫狀態的深入解析。 下列各節顯示範例log4j2和logback組態，以在啟用詳細資訊記錄時減少過多的訊息。

設定 Log4J 2

使用下列步驟來設定Log4J 2：

  1. 使用記錄範例 pom.xml 中的相依性，在 Log4j2 所需的相依性一節中新增 pom.xml 中的相依性。
  2. 將 log4j2.xml 新增至 src/main/resources 資料夾。

設定記錄備份

使用下列步驟來設定記錄：

  1. 使用記錄範例 pom.xml 中的相依性新增 pom.xml 中的相依性，位於「記錄備份所需的相依性」一節中。
  2. 將 logback.xml 新增至 src/main/resources 資料夾。

啟用AMQP傳輸記錄

如果啟用客戶端記錄不足以診斷您的問題，您可以啟用記錄到基礎 AMQP 連結庫中的 檔案 Qpid Proton-J。 Qpid Proton-J 使用 java.util.logging。 您可以使用下一節中顯示的內容來建立組態檔來啟用記錄。 或者，設定 proton.trace.level=ALL 和您想要用於實作 java.util.logging.Handler 的組態選項。 如需實作類別及其選項，請參閱 Java 8 SDK 檔中的套件 java.util.logging 。

若要追蹤AMQP傳輸框架，請設定 PN_TRACE_FRM=1 環境變數。

範例 “logging.properties” 檔案

下列組態檔會將 Proton-J 的 TRACE 層級輸出記錄到 proton-trace.log 檔案：

handlers=java.util.logging.FileHandler
.level=OFF
proton.trace.level=ALL
java.util.logging.FileHandler.level=ALL
java.util.logging.FileHandler.pattern=proton-trace.log
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=[%1$tF %1$tr] %3$s %4$s: %5$s %n

減少記錄

減少記錄的其中一種方式是變更詳細資訊。 另一種方式是新增篩選，以排除記錄檔名稱套件，例如 com.azure.messaging.eventhubs 或 com.azure.core.amqp。 如需範例，請參閱設定Log4J 2和設定記錄檔小節中的 XML 檔案。

當您提交 Bug 時，下列套件中類別的記錄訊息很有趣：

  • com.azure.core.amqp.implementation
  • com.azure.core.amqp.implementation.handler
    • 例外狀況是您可以忽略 onDelivery 中的 ReceiveLinkHandler訊息。
  • com.azure.messaging.eventhubs.implementation

下一步

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