다음을 통해 공유


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 필드를 찾습니다.

    X-Ms-Skype-Chain-Id를 보여 주는 응답 헤더의 스크린샷

  • 작업을 실행한 후 애플리케이션이 수신하는 콜백 이벤트에서. 예를 들어 CallConnected 또는 PlayFailed의 경우 correlationID를 찾습니다.

    상관 관계 ID를 보여 주는 통화 연결 끊김 이벤트의 스크린샷

이러한 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에 액세스

프로그램 간략 ID는 Azure Portal의 규정 문서 블레이드에서 찾을 수 있습니다.

무료 확인 캠페인 간략 ID를 보여 주는 스크린샷.


이메일 작업 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를 찾으려면 다음 단계를 따릅니다.

  1. Azure Portal로 이동하고 자격 증명을 사용하여 Azure Portal에 로그인합니다.

  2. 왼쪽 창에서 Microsoft Entra ID를 선택합니다.

  3. Microsoft Entra ID의 개요 페이지에서 디렉터리(테넌트) ID를 복사하여 애플리케이션 코드에 저장합니다.

    Microsoft Entra 테넌트 ID를 복사하고 저장하는 방법을 보여 주는 스크린샷.

애플리케이션 ID 가져오기

애플리케이션 ID를 찾으려면 다음 단계를 따릅니다.

  1. Azure Portal로 이동하고 자격 증명을 사용하여 Azure Portal에 로그인합니다.

  2. 왼쪽 창에서 Microsoft Entra ID를 선택합니다.

  3. Microsoft Entra ID의 앱 등록에서 애플리케이션을 선택합니다.

  4. 애플리케이션 ID를 복사하고 애플리케이션 코드에 저장합니다.

    Microsoft Entra 애플리케이션 ID를 복사하고 저장하는 방법을 보여 주는 스크린샷.

    디렉터리(테넌트) ID는 애플리케이션 개요 페이지에서도 찾을 수 있습니다.

사용자 ID 가져오기

사용자 ID를 찾으려면 다음 단계를 따릅니다.

  1. Azure Portal로 이동하고 자격 증명을 사용하여 Azure Portal에 로그인합니다.

  2. 왼쪽 창에서 Microsoft Entra ID를 선택합니다.

  3. Microsoft Entra ID의 사용자에서 사용자를 선택합니다.

  4. Microsoft Entra 사용자의 프로필 페이지에서 개체 ID 복사하여 애플리케이션 코드에 저장합니다.

    Microsoft Entra 사용자 ID를 복사하고 저장하는 방법을 보여 주는 스크린샷.

변경 불가능한 리소스 ID 가져오기

경우에 따라 Communication Service 리소스의 변경 불가능한 리소스 ID를 제공해야 할 수도 있습니다. 이를 찾으려면 다음 단계를 따릅니다.

  1. Azure Portal로 이동하고 자격 증명을 사용하여 Azure Portal에 로그인합니다.
  2. Communication Service 리소스를 엽니다.
  3. 왼쪽 창에서 개요선택하고 JSON 보기통신 리소스 개요를 JSON 보기로 전환하는 방법을 보여 주는 스크린샷.로 전환합니다.
  4. 리소스 JSON 페이지에서 immutableResourceId 값을 복사하여 지원 팀에 제공합니다. 리소스 JSON의 스크린샷

Teams 사용자에 대한 Azure Communication Services 지원을 사용하기 위한 Teams 라이선스 자격 확인

Teams 사용자에 대한 Azure Communication Services 지원을 사용하기 위한 Teams 라이선스 자격을 확인하는 다음 두 가지 방법이 있습니다.

  • Teams 웹 클라이언트를 통한 확인
  • Microsoft Graph API를 통한 현재 Teams 라이선스 확인

Teams 웹 클라이언트를 통한 확인

Teams 웹 클라이언트를 통해 Teams 라이선스 자격을 확인하려면 다음 단계를 따릅니다.

  1. 브라우저를 열고, Teams 웹 클라이언트로 이동합니다.
  2. 유효한 Teams 라이선스가 있는 자격 증명으로 로그인합니다.
  3. 인증에 성공하고 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 탐색기 도구를 사용하여 사용자에게 할당된 라이선스를 확인합니다.

  1. 브라우저를 열고, Graph 탐색기로 이동합니다.

  2. 자격 증명을 사용하여 Graph 탐색기에 로그인합니다. Graph 탐색기에 로그인하는 방법의 스크린샷

  3. 쿼리 상자에서 다음 API를 입력하고, 쿼리 실행을 클릭합니다.

    https://graph.microsoft.com/v1.0/me/licenseDetails
    

    Graph 탐색기에서 API를 입력하는 방법의 스크린샷

    또는 다음 API를 통해 사용자 ID를 제공하여 특정 사용자를 쿼리할 수 있습니다.

    https://graph.microsoft.com/v1.0/users/{id}/licenseDetails
    
  4. 응답 미리 보기 창에 다음과 같은 출력이 표시됩니다.

    여기에 표시된 응답 개체는 가독성을 위해 단축될 수 있습니다.

    {
        "@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"
                    }
                ]
            }
        ]
    }
    
  5. 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 알 수 없는 오류/실패로 인해 메시지를 전송하지 못했습니다. 메시지 다시 보내기를 시도합니다.