Azure Communication Services의 문제 해결
이 문서는 Communication Services 솔루션에서 발생할 수 있는 문제를 해결하는 데 도움이 됩니다. SMS 문제를 해결하는 경우 Event Grid를 통해 전달 보고를 사용하여 SMS 전달 세부 정보를 캡처할 수 있습니다.
도움말 가져오기
개발자는 질문을 제출하고, 기능을 제안하고, 문제를 보고하는 것이 좋습니다. 도움을 지원하기 위한 지원 옵션 목록을 보여주는 전용 지원 및 도움말 옵션 페이지가 마련되어 있습니다.
특정 유형의 문제를 해결하는 데 도움이 되도록 다음 정보 중 하나를 입력하라는 메시지가 표시될 수 있습니다.
- MS-CV ID: 이 ID는 호출 및 메시지 문제를 해결하는 데 사용됩니다.
- 호출 ID: 이 ID는 Communication Services 호출을 식별하는 데 사용됩니다.
- SMS 메시지 ID: 이 ID는 SMS 메시지를 식별하는 데 사용됩니다.
- 짧은 코드 프로그램 간략한 ID: 이 ID는 짧은 코드 프로그램 간략한 애플리케이션을 식별하는 데 사용됩니다.
- 무료 확인 캠페인 간략 ID: 이 ID는 무료 확인 캠페인 요약 애플리케이션을 식별하는 데 사용됩니다.
- Email 메시지 ID: 이 ID는 이메일 보내기 요청을 식별하는 데 사용됩니다.
- 상관 관계 ID: 이 ID는 통화 자동화를 사용하여 수행된 요청을 식별하는 데 사용됩니다.
- 호출 로그: 이러한 로그에는 호출 및 네트워크 문제를 해결하는 데 사용할 수 있는 자세한 정보가 포함되어 있습니다.
제한 및 한도에 대한 자세한 내용은 서비스 제한 문서도 참조하세요.
MS CV ID에 액세스
MS-CV ID는 SDK를 초기화할 때 clientOptions
개체 인스턴스에서 진단을 구성하여 액세스할 수 있습니다. 채팅, ID 및 VoIP 호출을 비롯한 모든 Azure SDK에 대해 진단을 구성할 수 있습니다.
클라이언트 옵션 예제
다음 코드 조각에서는 진단 구성을 보여줍니다. 진단이 활성화된 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) });
통화 자동화에 필요한 액세스 ID
호출 관리 또는 레코딩 문제와 같은 통화 자동화 SDK와 관련된 문제를 해결하는 경우 실패한 호출 또는 작업을 식별하는 데 도움이 되는 ID를 수집해야 합니다. 여기서 언급하는 두 ID 중 하나를 제공할 수 있습니다.
API 응답 헤더에서
X-Ms-Skype-Chain-Id
필드를 찾습니다.작업을 실행한 후 애플리케이션이 수신하는 콜백 이벤트에서. 예를 들어
CallConnected
또는PlayFailed
의 경우 correlationID를 찾습니다.
이러한 ID 중 하나 외에도 실패한 사용 사례에 대한 세부 정보와 실패가 관찰된 타임스탬프를 제공합니다.
클라이언트 호출 ID에 액세스
음성 또는 화상 통화 문제를 해결할 때 call ID
를 제공하라는 메시지가 표시될 수 있습니다. 이 값은 call
개체의 id
속성을 통해 액세스할 수 있습니다.
// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)
SMS 메시지 ID에 액세스
SMS 문제의 경우 응답 개체에서 메시지 ID를 수집할 수 있습니다.
// 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
}
짧은 코드 프로그램 간략한 ID에 액세스
프로그램 간략한 ID는 Azure Portal의 [짧은 코드] 블레이드에서 찾을 수 있습니다.
무료 확인 캠페인 간략 ID에 액세스
프로그램 간략 ID는 Azure Portal의 규정 문서 블레이드에서 찾을 수 있습니다.
이메일 작업 ID에 액세스
이메일 보내기 또는 이메일 메시지 상태 요청 문제를 해결하는 경우, 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 Communication Services 통화 SDK는 내부적으로 @azure/logger 라이브러리를 사용하여 로깅을 제어합니다.
@azure/logger
패키지의 setLogLevel
메서드를 사용하여 로그 출력 수준을 구성합니다. 로거를 만들고 CallClient 생성자에 전달합니다.
import { setLogLevel, createClientLogger, AzureLogger } from '@azure/logger';
setLogLevel('verbose');
let logger = createClientLogger('ACS');
const callClient = new CallClient({ logger });
AzureLogger를 사용하여 AzureLogger.log
메서드를 재정의하여 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 Communication Services 통화 SDK가 로그 파일에 대한 액세스를 제공합니다.
네이티브 SDK 통화의 경우 로그 파일 액세스 자습서를 참조하세요.
UI 라이브러리(Android, iOS)
Android 또는 iOS용 Azure Communication Services UI 라이브러리를 사용하는 경우 기본 제공 지원 양식을 통해 사용자 피드백을 요청받을 수 있습니다.
통화 UI 지원 양식의 지원 기능을 사용하는 방법에 관한 자세한 내용은 지원 양식 통합 자습서를 참조하세요. 이 문서에서는 필요한 이벤트 처리기를 추가하고 지원 정보를 중앙에 저장하기 위한 기본 클라이언트/서버를 구현하는 방법을 설명합니다. 이 가이드는 조직에서 사용하는 지원 서비스와 통합하는 경로를 안내하기 위한 것입니다.
ACS 통합에서 종단 간 지원 흐름 구축
통화 SDK와 통화 UI SDK 중 어떤 것을 사용하든, 최종 사용자를 위한 지원 제공은 강력한 통합의 핵심 구성 요소입니다. 다음 문서에서는 지원 피드백 루프의 각 지점에서 주요 고려 사항을 강조하고 자세한 내용을 알아볼 수 있는 지점을 제공합니다.
Microsoft Entra 정보 찾기
- 디렉터리 ID 가져오기
- 애플리케이션 ID 가져오기
- 사용자 ID 가져오기
디렉터리 ID 가져오기
디렉터리(테넌트) ID를 찾으려면 다음 단계를 따릅니다.
Azure Portal로 이동하고 자격 증명을 사용하여 Azure Portal에 로그인합니다.
왼쪽 창에서 Microsoft Entra ID를 선택합니다.
Microsoft Entra ID의 개요 페이지에서 디렉터리(테넌트) ID를 복사하여 애플리케이션 코드에 저장합니다.
애플리케이션 ID 가져오기
애플리케이션 ID를 찾으려면 다음 단계를 따릅니다.
Azure Portal로 이동하고 자격 증명을 사용하여 Azure Portal에 로그인합니다.
왼쪽 창에서 Microsoft Entra ID를 선택합니다.
Microsoft Entra ID의 앱 등록에서 애플리케이션을 선택합니다.
애플리케이션 ID를 복사하고 애플리케이션 코드에 저장합니다.
디렉터리(테넌트) ID는 애플리케이션 개요 페이지에서도 찾을 수 있습니다.
사용자 ID 가져오기
사용자 ID를 찾으려면 다음 단계를 따릅니다.
Azure Portal로 이동하고 자격 증명을 사용하여 Azure Portal에 로그인합니다.
왼쪽 창에서 Microsoft Entra ID를 선택합니다.
Microsoft Entra ID의 사용자에서 사용자를 선택합니다.
Microsoft Entra 사용자의 프로필 페이지에서 개체 ID 복사하여 애플리케이션 코드에 저장합니다.
변경 불가능한 리소스 ID 가져오기
경우에 따라 Communication Service 리소스의 변경 불가능한 리소스 ID를 제공해야 할 수도 있습니다. 이를 찾으려면 다음 단계를 따릅니다.
- Azure Portal로 이동하고 자격 증명을 사용하여 Azure Portal에 로그인합니다.
- Communication Service 리소스를 엽니다.
- 왼쪽 창에서 개요선택하고 JSON 보기
로 전환합니다.
- 리소스 JSON 페이지에서
immutableResourceId
값을 복사하여 지원 팀에 제공합니다.
Teams 사용자에 대한 Azure Communication Services 지원을 사용하기 위한 Teams 라이선스 자격 확인
Teams 사용자에 대한 Azure Communication Services 지원을 사용하기 위한 Teams 라이선스 자격을 확인하는 다음 두 가지 방법이 있습니다.
- Teams 웹 클라이언트를 통한 확인
- Microsoft Graph API를 통한 현재 Teams 라이선스 확인
Teams 웹 클라이언트를 통한 확인
Teams 웹 클라이언트를 통해 Teams 라이선스 자격을 확인하려면 다음 단계를 따릅니다.
- 브라우저를 열고, Teams 웹 클라이언트로 이동합니다.
- 유효한 Teams 라이선스가 있는 자격 증명으로 로그인합니다.
- 인증에 성공하고 https://teams.microsoft.com/ 도메인에 남아 있는 경우 Teams 라이선스를 사용할 수 있습니다. 인증에 실패하거나 https://teams.live.com/v2/ 도메인으로 리디렉션되는 경우 Teams 라이선스는 Teams 사용자에 대한 Azure Communication Services 지원을 사용할 수 없습니다.
Microsoft Graph API를 통한 현재 Teams 라이선스 확인
사용자에게 할당된 라이선스를 반환하는 licenseDetails Microsoft Graph API를 사용하여 현재 Teams 라이선스를 확인할 수 있습니다. 다음 단계에 따라 Graph 탐색기 도구를 사용하여 사용자에게 할당된 라이선스를 확인합니다.
브라우저를 열고, Graph 탐색기로 이동합니다.
자격 증명을 사용하여 Graph 탐색기에 로그인합니다.
쿼리 상자에서 다음 API를 입력하고, 쿼리 실행을 클릭합니다.
https://graph.microsoft.com/v1.0/me/licenseDetails
또는 다음 API를 통해 사용자 ID를 제공하여 특정 사용자를 쿼리할 수 있습니다.
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
속성에 적격 팀 라이선스 표의 값 중 하나가 있는 라이선스 세부 정보를 찾습니다.
SDK 오류 코드 호출
Azure Communication Services Calling SDK는 다음 오류 코드를 사용하여 통화 문제를 해결하는 데 도움을 줍니다. 이러한 오류 코드는 통화가 종료된 후 call.callEndReason
속성을 통해 노출됩니다.
오류 코드 | 설명 | 수행할 작업 |
---|---|---|
403 | 금지 / 인증 오류. | Communication Services 토큰이 유효하고 만료되지 않았는지 확인합니다. |
404 | 호출을 찾을 수 없습니다. | 통화하는 번호(또는 조인하는 통화)가 있는지 확인합니다. |
408 | 통화 컨트롤러 시간이 초과되었습니다. | 사용자 엔드포인트에서 프로토콜 메시지를 기다리는 동안 통화 컨트롤러 시간이 초과되었습니다. 클라이언트가 연결되어 있고 사용 가능한지 확인합니다. |
410 | 로컬 미디어 스택 또는 미디어 인프라 오류입니다. | 지원되는 환경에서 최신 SDK를 사용하고 있는지 확인합니다. |
430 | 클라이언트 애플리케이션에 메시지를 전달할 수 없습니다. | 클라이언트 애플리케이션이 실행 중이고 사용 가능한지 확인합니다. |
480 | 원격 클라이언트 엔드포인트가 등록되지 않았습니다. | 원격 엔드포인트를 사용할 수 있는지 확인합니다. |
481 | 들어오는 호출을 처리하지 못했습니다. | Azure Portal을 통해 지원 요청을 제출합니다. |
487 | 엔드포인트 불일치 문제로 인해 통화가 취소되거나, 로컬에서 거부되거나, 종료되었거나 미디어 제품을 생성하지 못했습니다. | 예상 동작. |
490, 491, 496, 497, 498 | 로컬 엔드포인트 네트워크 문제. | 네트워크를 확인합니다. |
500, 503, 504 | Communication Services 인프라 오류입니다. | Azure Portal을 통해 지원 요청을 제출합니다. |
603 | 원격 Communication Services 참가자가 전역적으로 거부한 호출 | 예상 동작. |
통화 자동화 SDK 오류 코드
통화 자동화 SDK에서 표시되는 오류 코드는 아래와 같습니다.
오류 코드 | 설명 | 수행할 작업 |
---|---|---|
400 | Bad request | 입력 요청이 잘못되었습니다. 오류 메시지를 확인하여 잘못된 입력을 확인합니다. |
400 | 재생 실패 | 오디오 파일이 WAV, 16KHz, Mono인지, 그리고 파일 URL에 공개적으로 액세스할 수 있는지 확인합니다. |
400 | 인식 실패 | 오류 메시지를 확인합니다. 시간 제한에 도달했거나 작업이 취소된 경우 메시지가 강조 표시됩니다. 오류 코드 및 메시지에 대한 자세한 내용은 사용자 입력 수집 방법 가이드를 확인하세요. |
401 | Unauthorized | HMAC 인증에 실패했습니다. CallAutomationClient를 만드는 데 사용한 연결 문자열이 올바른지 확인합니다. |
403 | 금지 | 요청이 금지되었습니다. 액세스하려는 리소스에 액세스할 수 있는 권한이 있는지 확인합니다. |
404 | 리소스를 찾을 수 없음 | 작업을 수행하려는 통화가 존재하지 않습니다. 예를 들어 이미 연결이 끊긴 통화를 전송하는 경우입니다. |
429 | Too many requests | Retry-After 헤더에 제안된 지연 후 다시 시도한 다음, 기하급수적으로 백오프합니다. |
500 | 내부 서버 오류 | 지연 후 다시 시도합니다. 오류가 계속되면 지원 티켓을 제출하세요. |
500 | 재생 실패 | Azure Portal을 통해 지원 요청을 제출합니다. |
500 | 인식 실패 | 오류 메시지를 확인하고 오디오 파일 형식(WAV, 16KHz, Mono)이 유효한지 확인합니다. 파일 형식이 유효한 경우 Azure Portal을 통해 지원 요청을 제출합니다. |
502 | 나쁜 게이트웨이 | 새 http 클라이언트를 사용하여 지연 후 다시 시도합니다. |
특정 문제를 해결하는 경우 아래 팁을 고려합니다.
- 애플리케이션에서 IncomingCall Event Grid 이벤트를 받지 못하고 있음: 이벤트 구독을 만들 때 애플리케이션 엔드포인트가 Event Grid를 사용하여 유효성 검사되었는지 확인합니다. 유효성 검사에 성공하면 이벤트 구독에 대한 프로비전 상태가 성공으로 표시됩니다.
- 'CallbackUri 필드가 잘못되었습니다.' 오류 발생: 통화 자동화는 HTTP 엔드포인트를 지원하지 않습니다. 제공하는 콜백 URL에서 HTTPS를 지원하는지 확인합니다.
- PlayAudio 작업에서 아무 것도 재생하지 않음: 현재 오디오 파일에는 웨이브 파일(.wav) 형식만 지원됩니다. 웨이브 파일의 오디오 콘텐츠는 16,000(16KHz) 샘플링 속도의 모노(단일 채널) 16비트 샘플이어야 합니다.
- PSTN 엔드포인트에 대한 작업이 작동하지 않음: 전화 번호에 대한 CreateCall, Transfer, AddParticipant 및 Redirect를 수행하려면 작업 요청에서 SourceCallerId를 설정해야 합니다. 직접 라우팅을 사용하지 않는 경우 작업이 성공하려면 원본 호출자 ID가 Communication Services 리소스에서 소유한 전화 번호여야 합니다.
제품 팀에서 추적하고 있는 알려진 문제에 대해 알아보려면 이 문서를 참조하세요.
채팅 SDK 오류 코드
Azure Communication Services 채팅 SDK는 다음 오류 코드를 사용하여 채팅 문제를 해결하는 데 도움을 줍니다. 오류 코드는 오류 응답에서 error.code
속성을 통해 노출됩니다.
오류 코드 | 설명 | 수행할 작업 |
---|---|---|
401 | Unauthorized | Communication Services 토큰이 유효하고 만료되지 않았는지 확인합니다. |
403 | 금지 | 요청한 사람이 리소스에 액세스할 수 있는지 확인합니다. |
429 | Too many requests | 클라이언트 쪽 애플리케이션이 사용자에게 친숙한 방식으로 이 시나리오를 처리하는지 확인합니다. 오류가 계속되면 지원 요청을 제출하세요. |
503 | Service Unavailable | Azure Portal을 통해 지원 요청을 제출합니다. |
SMS 오류 코드
Azure Communication Services SMS SDK는 다음 오류 코드를 사용하여 SMS 문제를 해결하는 데 도움을 줍니다. 오류 코드는 SMS 전송 보고서의 "DeliveryStatusDetails" 필드를 통해 표시됩니다.
오류 코드 | 설명 | 수행할 작업 |
---|---|---|
2000 | 메시지가 성공적으로 전송되었습니다. | |
4000 | 사기 감지로 인해 메시지가 거부되었습니다. | 번호에 허용되는 최대 메시지 수를 초과하지 않는지 확인합니다. |
4001 | 잘못된 원본/보낸 사람 번호 형식으로 인해 메시지가 거부되었습니다. | 받는 사람 번호가 E.164 형식이고 보낸 사람 번호가 E.164 또는 짧은 코드 형식인지 확인합니다. |
4002 | 잘못된 대상/받는 사람 번호 형식으로 인해 메시지가 거부되었습니다. | 받는 사람 번호가 E.164 형식인지 확인합니다. |
4003 | 지원되지 않는 대상으로 인해 메시지를 전송하지 못했습니다. | 보내려는 대상이 지원되는지 확인합니다. |
4004 | 존재하지 않는 대상/받는 사람 번호로 인해 메시지를 전송하지 못했습니다. | 보내고 있는 받는 사람의 번호가 유효한지 확인합니다. |
4005 | 대상 이동 통신 사업자가 메시지를 차단했습니다. | |
4006 | 대상/받는 사람 번호에 연결할 수 없습니다. | 나중에 메시지 다시 보내기를 시도합니다. |
4007 | 대상/받는 사람 번호가 사용자의 메시지 수신을 옵트아웃했습니다. | 번호에 대한 추가 메시지 시도가 수행되지 않도록 대상/받는 사람 번호를 '옵트아웃했음'으로 표시합니다. |
4008 | 프로필에 허용되는 최대 메시지 수를 초과했습니다. | 번호에 허용되는 최대 메시지 수를 초과하지 않았는지 확인하거나 큐를 사용하여 메시지를 일괄 처리합니다. |
4009 | 메시지가 Microsoft 권한 시스템에서 거부되었습니다. | 사기 행위가 감지되면 이 오류가 자주 발생합니다. 자세한 내용은 지원 팀에 문의하세요. |
4010 | 확인되지 않는 무료 전화 번호로 인해 메시지가 차단되었습니다. | 확인되지 않는 보내기 제한을 검토하고 가능한 한 빨리 무료 전화 번호 확인을 제출합니다. |
5000 | 메시지를 전송하지 못했습니다. 자세한 내용은 Microsoft 지원 팀에 문의하세요. | Azure Portal을 통해 지원 요청을 제출합니다. |
5001 | 애플리케이션/시스템의 일시적인 사용 불가능으로 인해 메시지를 전송하지 못했습니다. | |
5002 | 이동 통신 사업자는 전달 보고서를 지원하지 않습니다. | 이동 통신 사업자가 전달 보고서를 지원하지 않는 경우 이 오류가 자주 발생합니다. 메시지가 이미 전달되었을 수 있으므로 아무 작업도 필요하지 않습니다. |
9999 | 알 수 없는 오류/실패로 인해 메시지를 전송하지 못했습니다. | 메시지 다시 보내기를 시도합니다. |
관련 정보
피드백
https://aka.ms/ContentUserFeedback
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요.다음에 대한 사용자 의견 제출 및 보기