Azure 通訊服務 中的疑難解答
本文件可協助您針對通訊服務解決方案中可能會遇到的問題進行疑難解答。 如果您要針對SMS進行疑難解答，您可以使用 事件方格 啟用傳遞報告，以擷取 SMS 傳遞詳細數據。
取得說明
我們鼓勵開發人員提交問題、建議功能，並將問題回報為問題。 為了協助取得協助，我們有一個 專用的支持和說明選項頁面 ，列出您的支持選項。
為了協助您針對特定類型的問題進行疑難解答，系統可能會要求您提供下列任一項資訊：
- MS-CV 識別碼：此標識符可用來針對呼叫和訊息進行疑難解答。
- 通話標識碼：此標識碼用來識別通訊服務呼叫。
- SMS 訊息識別碼：此標識碼用來識別SMS訊息。
- 簡短程式簡短標識碼：此標識碼可用來識別簡短的程式碼程式簡短應用程式。
- 免付費驗證活動簡短標識碼：此標識碼用來識別免付費驗證活動簡短應用程式。
- 電子郵件訊息識別碼：此標識碼用來識別傳送電子郵件要求。
- 相互關聯標識碼：此標識碼可用來識別使用通話自動化提出的要求。
- 通話記錄：這些記錄包含詳細資訊可用來針對通話和網路問題進行疑難解答。
另請參閱我們的服務 限制 檔，以取得節流和限制的詳細資訊。
存取您的 MS-CV 識別碼
初始化 SDK 時，可以在物件實例中 clientOptions 設定診斷，以存取 MS-CV 識別符。 您可以針對任何 Azure SDK 設定診斷，包括聊天、身分識別和 VoIP 通話。
用戶端選項範例
下列代碼段示範診斷設定。 當 SDK 與啟用診斷搭配使用時，診斷詳細數據可以發出給已設定的事件接聽程式：
// 1. Import Azure.Core.Diagnostics
using Azure.Core.Diagnostics;
// 2. Initialize an event source listener instance
using var listener = AzureEventSourceListener.CreateConsoleLogger();
Uri endpoint = new Uri("https://<RESOURCE-NAME>.communication.azure.net");
var (token, communicationUser) = await GetCommunicationUserAndToken();
CommunicationUserCredential communicationUserCredential = new CommunicationUserCredential(token);
// 3. Setup diagnostic settings
var clientOptions = new ChatClientOptions()
{
Diagnostics =
{
LoggedHeaderNames = { "*" },
LoggedQueryParameters = { "*" },
IsLoggingContentEnabled = true,
}
};
// 4. Initialize the ChatClient instance with the clientOptions
ChatClient chatClient = new ChatClient(endpoint, communicationUserCredential, clientOptions);
ChatThreadClient chatThreadClient = await chatClient.CreateChatThreadAsync("Thread Topic", new[] { new ChatThreadMember(communicationUser) });
通話自動化所需的存取標識碼
針對通話自動化 SDK 的問題進行疑難解答，例如通話管理或錄製問題時，您需要收集標識碼，以協助識別失敗的通話或作業。 您可以提供這裡所述的兩個標識碼之一。
從 API 回應的標頭中，找出 欄位
X-Ms-Skype-Chain-Id。
從應用程式在執行動作之後收到的回呼事件。 例如
CallConnected或PlayFailed，找出 correlationID。
除了其中一個標識碼，請提供失敗使用案例的詳細數據，以及觀察到失敗時的時間戳。
存取您的用戶端通話識別碼
針對語音或視訊通話進行疑難解答時，系統可能會要求您提供 call ID。 這個值可以透過 id 物件的屬性 call 來存取：
// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)
存取您的SMS訊息識別碼
針對SMS問題，您可以從回應物件收集訊息識別碼。
// Instantiate the SMS client
const smsClient = new SmsClient(connectionString);
async function main() {
const result = await smsClient.send({
from: "+18445792722",
to: ["+1972xxxxxxx"],
message: "Hello World 👋🏻 via Sms"
}, {
enableDeliveryReport: true // Optional parameter
});
console.log(result); // your message ID is in the result
}
存取您的簡短程式簡短標識碼
您可以在 [簡短代碼] 刀鋒視窗的 [Azure 入口網站 中找到程序簡短標識符。
存取免付費驗證營銷活動簡短標識符
您可以在 [法規檔] 刀鋒視窗的 [Azure 入口網站 中找到程序簡短標識符。
存取您的電子郵件作業識別碼
針對傳送電子郵件或電子郵件訊息狀態要求進行疑難解答時，系統可能會要求您提供 operation ID。 您可以在回應中存取此值：
var emailSendOperation = await emailClient.SendAsync(
wait: WaitUntil.Completed,
senderAddress: sender,
recipientAddress: recipient,
subject: subject,
htmlContent: htmlContent);
/// Get the OperationId so that it can be used for tracking the message for troubleshooting
Console.WriteLine($"Email operation id = {emailSendOperation.Id}");
存取呼叫 SDK 中的支持檔案
呼叫 SDK 提供方便的方法，以取得記錄檔的存取權。 這些檔案可為 Microsoft 支援專家和工程師提供寶貴的服務。 建議在偵測到問題時主動收集這些記錄。
啟用和存取通話記錄
[JavaScript]
Azure 通訊服務呼叫 SDK 內部依賴@azure/記錄器連結庫來控制記錄。
setLogLevel使用封裝中的 @azure/logger 方法來設定記錄輸出層級。 建立記錄器，並將其傳遞至 CallClient 建構函式：
import { setLogLevel, createClientLogger, AzureLogger } from '@azure/logger';
setLogLevel('verbose');
let logger = createClientLogger('ACS');
const callClient = new CallClient({ logger });
您可以覆寫 AzureLogger.log 方法，使用 AzureLogger 來重新導向 Azure SDK 的記錄輸出：您可以登入瀏覽器控制台、檔案、緩衝區、傳送至我們自己的服務等等。如果您要透過網路將記錄傳送至您自己的服務，請勿為每個記錄行傳送要求，因為這會影響瀏覽器效能。 相反地，請累積記錄行，並以批次方式傳送它們。
// Redirect log output
AzureLogger.log = (...args) => {
// To console, file, buffer, REST API, etc...
console.log(...args);
};
原生 SDK （Android/iOS）
針對 Android、iOS 和 Windows，Azure 通訊服務 呼叫 SDK 提供記錄檔的存取權。
如需呼叫原生 SDK，請參閱 記錄檔存取教學課程
UI 連結庫 （Android， iOS）
如果您使用適用於 Android 或 iOS 的 Azure 通訊服務 UI 連結庫，則可以透過內建支援表單來徵求使用者意見反應。
如需如何使用呼叫UI支援表單支援功能的詳細資訊，請參閱 支援表單整合教學課程。 本文件會引導您新增必要的事件處理程式，以及建立基本用戶端/伺服器實作，以集中儲存支持資訊。 本指南的設計訴求是引導您走上與組織所使用支援服務整合的道路。
在 ACS 整合中建置端對端支援流程
無論您是使用通話 SDK 或通話 UI SDK，都提供對終端用戶的支援，都是任何強固整合的重要元件。 下列文件強調支援意見反應迴圈的每個時間點的重要考慮，並提供跳躍點以深入瞭解。
尋找 Microsoft Entra 資訊
- 取得目錄識別碼
- 取得應用程式識別碼
- 取得使用者標識碼
取得目錄識別碼
若要尋找您的目錄（租用戶）標識碼，請遵循下列步驟：
流覽至 Azure 入口網站，並使用認證登入 Azure 入口網站。
從左窗格中，選取 [Microsoft Entra ID]。
從 Microsoft Entra ID 的 [概觀 ] 頁面，複製目錄 （租使用者） 識別碼，並將其儲存在您的應用程式程式代碼中。
取得應用程式識別碼
若要尋找您的應用程式識別碼，請遵循下列步驟：
流覽至 Azure 入口網站，並使用認證登入 Azure 入口網站。
從左窗格中，選取 [Microsoft Entra ID]。
從 Microsoft Entra ID 中的 應用程式註冊，選取您的應用程式。
複製應用程式 識別碼 ，並將其儲存在您的應用程式程式代碼中。
您也可以在應用程式概觀頁面中找到目錄（租使用者）標識碼。
取得使用者標識碼
若要尋找您的使用者識別碼，請遵循下列步驟：
流覽至 Azure 入口網站，並使用認證登入 Azure 入口網站。
從左窗格中，選取 [Microsoft Entra ID]。
從 Microsoft Entra 識別碼中的 [使用者 ]，選取您的使用者。
從 Microsoft Entra 使用者的 [設定檔 ] 頁面，複製 [物件識別符 ]，並將其儲存在您的應用程式程式碼中。
取得不可變的資源標識碼
有時候，您也需要提供通訊服務資源的不可變資源識別碼。 若要尋找它，請遵循下列步驟：
- 流覽至 Azure 入口網站，並使用認證登入 Azure 入口網站。
- 開啟您的通訊服務資源。
- 從左窗格中選取 [概觀]，然後切換至 JSON 檢視
- 從 [資源 JSON] 頁面複製
immutableResourceId值，並將其提供給支援小組。
驗證 Teams 授權資格，以使用 Teams 使用者的 Azure 通訊服務 支援
有兩種方式可驗證 Teams 授權資格，以使用 Teams 使用者的 Azure 通訊服務 支援：
- 透過 Teams Web 用戶端進行驗證
- 透過 Microsoft Graph API 檢查您目前的 Teams 授權
透過 Teams Web 用戶端進行驗證
若要透過Teams Web用戶端驗證Teams授權資格，請遵循下列步驟：
- 開啟瀏覽器並流覽至 Teams Web 用戶端。
- 使用具有有效 Teams 授權的認證登入。
- 如果驗證成功，且您仍留在網域中 https://teams.microsoft.com/ ，則您的Teams授權符合資格。 如果驗證失敗，或您重新導向至https://teams.live.com/v2/網域，則您的Teams授權不符合使用Teams使用者的Azure 通訊服務支持資格。
透過 Microsoft Graph API 檢查您目前的 Teams 授權
您可以使用 licenseDetails Microsoft Graph API 找到目前的 Teams 授權，以傳回指派給使用者的授權。 請遵循下列步驟，使用 Graph 總管工具來檢視指派給使用者的授權：
開啟瀏覽器並流覽至 Graph 總管
使用認證登入 Graph 總管。
在查詢方塊中，輸入下列 API，然後按兩下 [ 執行查詢 ] ：
https://graph.microsoft.com/v1.0/me/licenseDetails
或者，您可以使用下列 API 提供使用者識別碼來查詢特定使用者：
https://graph.microsoft.com/v1.0/users/{id}/licenseDetails[ 回應預覽 ] 窗格會顯示輸出，如下所示：
請注意，此處顯示的回應物件可能會縮短以取得可讀性。
{ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('071cc716-8147-4397-a5ba-b2105951cc0b')/assignedLicenses", "value": [ { "skuId": "b05e124f-c7cc-45a0-a6aa-8cf78c946968", "servicePlans":[ { "servicePlanId":"57ff2da0-773e-42df-b2af-ffb7a2317929", "servicePlanName":"TEAMS1", "provisioningStatus":"Success", "appliesTo":"User" } ] } ] }尋找授權詳細數據，其中 屬性
servicePlanName在 [合格 Teams 授權] 數據表中 具有其中一個值
呼叫 SDK 錯誤碼
Azure 通訊服務呼叫 SDK 會使用下列錯誤碼來協助您針對通話問題進行疑難解答。 這些錯誤碼會在呼叫結束之後透過 call.callEndReason 屬性公開。
| 錯誤碼 | 描述 | 要採取的動作 |
|---|---|---|
| 403 | 禁止/驗證失敗。 | 請確定您的通訊服務令牌有效且未過期。 |
| 404 | 找不到呼叫。 | 請確定您正在撥打的號碼存在（或正在加入的通話）。 |
| 408 | 通話控制器逾時。 | 呼叫控制器逾時等候來自用戶端點的通訊協定訊息。 確定客戶端已連線且可供使用。 |
| 410 | 本機媒體堆疊或媒體基礎結構錯誤。 | 請確定您在支持的環境中使用最新的 SDK。 |
| 430 | 無法將訊息傳遞至用戶端應用程式。 | 請確定用戶端應用程式正在執行且可供使用。 |
| 480 | 遠端用戶端端點未註冊。 | 請確定遠端端端點可供使用。 |
| 481 | 無法處理連入呼叫。 | 透過 Azure 入口網站 提出支援要求。 |
| 487 | 由於端點不符問題或無法產生媒體供應專案，呼叫已取消、在本機拒絕、終止。 | 預期的行為。 |
| 490, 491, 496, 497, 498 | 本機端點網路問題。 | 檢查您的網路。 |
| 500, 503, 504 | 通訊服務基礎結構錯誤。 | 透過 Azure 入口網站 提出支援要求。 |
| 603 | 遠端通訊服務參與者全域拒絕的通話 | 預期的行為。 |
呼叫自動化 SDK 錯誤碼
呼叫自動化 SDK 會公開下列錯誤碼。
| 錯誤碼 | 描述 | 要採取的動作 |
|---|---|---|
| 400 | 錯誤要求 | 輸入要求無效。 查看錯誤訊息，以判斷輸入不正確。 |
| 400 | 播放失敗 | 請確定您的音訊檔案為 WAV、16KHz、Mono，並確定檔案 URL 可公開存取。 |
| 400 | 辨識失敗 | 檢查錯誤訊息。 訊息會醒目提示此失敗是因為達到逾時或作業已取消。 如需錯誤碼和訊息的詳細資訊，您可以檢查我們的操作指南以 收集使用者輸入。 |
| 401 | 未經授權 | HMAC 驗證失敗。 確認用來建立 CallAutomationClient 的 連接字串 是否正確。 |
| 403 | 禁止 | 禁止要求。 請確定您可以存取您嘗試存取的資源。 |
| 404 | 找不到資源 | 您嘗試採取行動的呼叫不存在。 例如，轉移已中斷連線的呼叫。 |
| 429 | 太多要求 | 在 Retry-After 標頭中建議的延遲之後重試，然後以指數方式輪詢。 |
| 500 | 內部伺服器錯誤 | 延遲之後重試。 如果持續存在，請提出支援票證。 |
| 500 | 播放失敗 | 透過 Azure 入口網站 提出支援要求。 |
| 500 | 辨識失敗 | 檢查錯誤訊息，並確認音訊檔格式有效 （WAV， 16KHz， Mono），如果檔格式有效，則透過 Azure 入口網站 提出支援要求。 |
| 502 | 閘道不正確 | 使用全新的 HTTP 用戶端延遲之後重試。 |
針對某些問題進行疑難解答時，請考慮下列秘訣。
- 您的應用程式未取得 IncomingCall 事件方格事件：請確定應用程式端點已在 建立事件訂用帳戶時向 Event Grid 驗證。 如果驗證成功，事件訂用帳戶的布建狀態會標示為成功。
- 取得錯誤「CallbackUri 字段無效」：呼叫自動化不支援 HTTP 端點。 請確定您提供的回呼 URL 支援 HTTPS。
- PlayAudio 宏指令不會播放任何動作：音訊檔案目前僅支援 Wave 檔案 （.wav） 格式。 波檔案中的音訊內容必須是單聲道（單聲道）、16 位樣本，且取樣率為 16,000（16KHz）。
- PSTN 端點上的動作無法運作：CreateCall、Transfer、AddParticipant 和 Redirect 至電話號碼會要求您在動作要求中設定 SourceCallerId。 除非您使用直接路由，否則來源來電者標識碼應該是通訊服務資源所擁有的電話號碼，動作才能成功。
請參閱本文，以了解產品小組正在追蹤的任何已知問題。
聊天 SDK 錯誤碼
Azure 通訊服務 Chat SDK 會使用下列錯誤碼來協助您針對聊天問題進行疑難解答。 錯誤碼會透過 error.code 錯誤回應中的 屬性公開。
| 錯誤碼 | 描述 | 要採取的動作 |
|---|---|---|
| 401 | 未經授權 | 請確定您的通訊服務令牌有效且未過期。 |
| 403 | 禁止 | 請確定要求的啟動器可以存取資源。 |
| 429 | 太多要求 | 請確定您的用戶端應用程式會以使用者易記的方式處理此案例。 如果錯誤持續發生，請提出支援要求。 |
| 503 | 服務無法使用 | 透過 Azure 入口網站 提出支援要求。 |
SMS 錯誤碼
Azure 通訊服務 SMS SDK 會使用下列錯誤碼來協助您針對 SMS 問題進行疑難解答。 錯誤碼會透過SMS傳遞報告中的 [DeliveryStatusDetails] 字段公開。
| 錯誤碼 | 描述 | 要採取的動作 |
|---|---|---|
| 2000 | 已成功傳遞訊息 | |
| 4000 | 郵件因詐騙偵測而遭到拒絕 | 請確定您未超過數目允許的訊息數目上限 |
| 4001 | 訊息因為來源/寄件者數位格式無效而遭到拒絕 | 確定 To number 為 E.164 格式，而 From number 格式為 E.164 或 Short 程式代碼格式 |
| 4002 | 訊息因為目的地/數位格式無效而遭到拒絕 | 確定 To 數位為 E.164 格式 |
| 4003 | 訊息因為不支援的目的地而無法傳遞 | 檢查您嘗試傳送的目標是否受到支援 |
| 4004 | 訊息無法傳遞，因為目的地/目的地號碼不存在 | 確定您傳送到的 [收信者] 號碼有效 |
| 4005 | 目的地電信業者封鎖訊息 | |
| 4006 | 無法連線到目的地/目的地號碼 | 請稍後嘗試重新傳送訊息 |
| 4007 | 目的地/收件者號碼已選擇不接收來自您的訊息 | 將目的地/目的地號碼標示為退出，如此就不會再嘗試對號碼進行任何訊息嘗試 |
| 4008 | 您已超過設定檔允許的訊息數目上限 | 請確定您未超過數目允許的訊息數目上限，或使用佇列來批處理訊息 |
| 4009 | Microsoft 權利系統拒絕郵件 | 通常，如果偵測到詐騙活動，就會發生這種情況。 如需詳細資訊，請連絡支持人員 |
| 4010 | 由於未驗證免付費電話號碼而封鎖訊息 | 檢閱未經驗證的傳送限制 ，並儘快提交免付費驗證 |
| 5000 | 訊息無法傳遞。 如需詳細資訊，請連絡 Microsoft 支援小組 | 透過 Azure 入口網站 提出支援要求 |
| 5001 | 由於應用程式/系統暫時無法使用，訊息無法傳遞 | |
| 5002 | 電信業者不支援傳遞報告 | 如果貨運公司不支援傳遞報告，則最常發生此情況。 訊息可能已經傳遞，因此不需要採取任何動作。 |
| 9999 | 訊息因為未知的錯誤/失敗而無法傳遞 | 嘗試重新傳送訊息 |