Share via

Pemecahan masalah di Azure Communication Services

  • Artikel

Dokumen ini membantu Anda memecahkan masalah yang mungkin Anda alami dalam solusi Communication Services Anda. Jika anda memecahkan masalah SMS, anda dapat mengaktifkan pelaporan pengiriman dengan Event Grid untuk menangkap detail pengiriman SMS.

Mendapatkan bantuan

Kami mendorong pengembang untuk mengirimkan pertanyaan, menyarankan fitur, dan melaporkan masalah. Untuk membantu mendapatkan bantuan, kami memiliki halaman opsi dukungan dan bantuan khusus yang mencantumkan opsi Anda untuk mendapatkan dukungan.

Untuk membantu Anda memecahkan masalah tertentu, Anda mungkin akan dimintai salah satu informasi berikut:

  • MS-CV ID: ID ini digunakan untuk memecahkan masalah panggilan dan pesan.
  • ID Panggilan: ID ini digunakan untuk mengidentifikasi panggilan Communication Services.
  • ID pesan SMS: ID ini digunakan untuk mengidentifikasi pesan SMS.
  • ID Singkat Program Kode Pendek: ID ini digunakan untuk mengidentifikasi aplikasi singkat program kode pendek.
  • ID singkat kampanye verifikasi bebas telunjuk: ID ini digunakan untuk mengidentifikasi aplikasi singkat kampanye verifikasi bebas telunjuk.
  • ID pesan email: ID ini digunakan untuk mengidentifikasi permintaan Kirim Email.
  • ID Korelasi: ID ini digunakan untuk mengidentifikasi permintaan yang dibuat menggunakan Automasi Panggilan.
  • Log panggilan: Log ini berisi informasi terperinci dapat digunakan untuk memecahkan masalah panggilan dan jaringan.

Lihat juga dokumentasi batas layanan kami untuk informasi lebih lanjut tentang pembatasan dan batasan.

Akses ID MS-CV Anda

ID MS-CV dapat diakses dengan mengonfigurasi diagnostik dalam instans objek clientOptions saat menginisialisasi SDK Anda. Diagnostik dapat dikonfigurasi untuk salah satu SDK Azure termasuk Obrolan, Identitas, dan Panggilan VoIP.

Contoh opsi klien

Cuplikan kode berikut menunjukkan konfigurasi diagnostik. Saat SDK digunakan dengan diagnostik diaktifkan, detail diagnostik dapat dipancarkan ke pendengar peristiwa yang dikonfigurasi:

// 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 Akses yang diperlukan untuk Automasi Panggilan

Saat memecahkan masalah dengan SDK Automasi Panggilan, seperti manajemen panggilan atau masalah perekaman, Anda perlu mengumpulkan ID yang membantu mengidentifikasi panggilan atau operasi yang gagal. Anda dapat memberikan salah satu dari dua ID yang disebutkan di sini.

  • Dari header respons API, temukan bidang X-Ms-Skype-Chain-Id.

    Cuplikan layar header respons memperlihatkan X-Ms-Skype-Chain-Id.

  • Dari peristiwa panggilan balik yang diterima aplikasi Anda setelah menjalankan tindakan. Misalnya CallConnected atau PlayFailed, temukan correlationID.

    Cuplikan layar peristiwa panggilan terputus memperlihatkan ID korelasi.

Selain salah satu ID ini, harap berikan detail tentang kasus penggunaan yang gagal dan tanda waktu ketika kegagalan diamati.

Akses ID panggilan klien Anda

Saat memecahkan masalah panggilan suara atau video, Anda mungkin diminta untuk menyediakan call ID. Nilai ini dapat diakses melalui id properti call objek:

// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)

Akses ID pesan SMS Anda

Untuk masalah SMS, Anda dapat mengambil ID pesan dari objek respons.

// 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
}

Akses ID singkat program kode pendek Anda

ID singkat program dapat ditemukan di portal Azure di bilah Kode Pendek.

Cuplikan layar memperlihatkan ID singkat program kode pendek.

Akses ID singkat kampanye verifikasi bebas telunjuk Anda

ID singkat program dapat ditemukan pada portal Azure di bilah Dokumen Peraturan.

Cuplikan layar memperlihatkan ID singkat kampanye verifikasi gratis telunjuk.

Mengakses ID operasi email Anda

Saat memecahkan masalah permintaan status kirim email atau pesan email, Anda mungkin diminta untuk memberikan operation ID. Nilai ini dapat diakses dalam respons:

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}");

Mengakses File Dukungan di SDK Panggilan

Memanggil SDK menyediakan metode kenyamanan untuk mendapatkan akses ke File Log. File-file ini dapat berfungsi berharga untuk spesialis dan insinyur dukungan Microsoft. Mengumpulkan log ini secara proaktif ketika masalah terdeteksi disarankan.

Mengaktifkan dan Mengakses Log Panggilan

[JavaScript]

SDK Panggilan Azure Communication Services bergantung secara internal pada pustaka @azure/pencatat untuk mengontrol pengelogan. setLogLevel Gunakan metode dari @azure/logger paket untuk mengonfigurasi tingkat output log. Buat pencatat dan teruskan ke konstruktor CallClient:

import { setLogLevel, createClientLogger, AzureLogger } from '@azure/logger';
setLogLevel('verbose');
let logger = createClientLogger('ACS');
const callClient = new CallClient({ logger });

Anda dapat menggunakan AzureLogger untuk mengalihkan output pengelogan dari Azure SDK dengan menimpa AzureLogger.log metode: Anda dapat masuk ke konsol browser, file, buffer, mengirim ke layanan kami sendiri, dll. Jika Anda akan mengirim log melalui jaringan ke layanan Anda sendiri, jangan mengirim permintaan per baris log karena ini akan memengaruhi performa browser. Sebagai gantinya, akumulasi baris log dan kirim dalam batch.

// Redirect log output
AzureLogger.log = (...args) => {
    // To console, file, buffer, REST API, etc...
    console.log(...args); 
};

SDK Asli (Android/iOS)

Untuk Android, iOS, dan Windows Azure Communication Services Calling SDK menawarkan akses ke file log.

Untuk Memanggil SDK Asli, lihat tutorial akses file log

Pustaka UI (Android, iOS)

Jika Anda menggunakan Pustaka UI Azure Communication Services untuk Android atau iOS, umpan balik pengguna dapat diminta melalui formulir dukungan bawaan.

Untuk informasi selengkapnya tentang cara menggunakan fungsionalitas dukungan formulir Dukungan Antarmuka Pengguna Panggilan, lihat tutorial integrasi Formulir Dukungan. Dokumen ini memandu Anda menambahkan penanganan aktivitas yang diperlukan, dan membuat implementasi klien/server dasar untuk penyimpanan informasi dukungan terpusat. Panduan ini dirancang untuk memandu Anda di jalur Menuju integrasi dengan layanan dukungan yang digunakan organisasi Anda.

Membangun Alur Dukungan menyeluruh dalam Integrasi ACS Anda

Baik Anda menggunakan SDK Panggilan atau Memanggil UI SDK, memberikan dukungan kepada pengguna akhir adalah komponen utama dari integrasi yang kuat. Dokumen berikut menyoroti pertimbangan utama di setiap titik perulangan umpan balik Dukungan, dan menyediakan titik lompat untuk mempelajari lebih lanjut.

Memberikan Dukungan Pengguna

Menemukan informasi Microsoft Entra

  • Mendapatkan ID Direktori
  • Mendapatkan ID Aplikasi
  • Mendapatkan ID Pengguna

Mendapatkan ID Direktori

Untuk menemukan ID Direktori (penyewa) Anda, ikuti langkah-langkah berikut:

  1. Navigasi ke portal Azure dan masuk ke portal Azure menggunakan kredensial.

  2. Dari panel kiri, pilih ID Microsoft Entra.

  3. Dari halaman Gambaran Umum di ID Microsoft Entra, salin ID Direktori (penyewa) dan simpan di kode aplikasi Anda.

    Cuplikan layar cara menyalin ID penyewa Microsoft Entra dan menyimpannya.

Mendapatkan ID Aplikasi

Untuk menemukan ID Aplikasi Anda, ikuti langkah-langkah berikut:

  1. Navigasi ke portal Azure dan masuk ke portal Azure menggunakan kredensial.

  2. Dari panel kiri, pilih ID Microsoft Entra.

  3. Dari Pendaftaran aplikasi di ID Microsoft Entra, pilih aplikasi Anda.

  4. Salin ID Aplikasi dan simpan di kode aplikasi Anda.

    Cuplikan layar cara menyalin ID aplikasi Microsoft Entra dan menyimpannya.

    ID direktori (penyewa) juga dapat ditemukan di halaman gambaran umum aplikasi.

Mendapatkan ID Pengguna

Untuk menemukan ID Pengguna Anda, ikuti langkah-langkah berikut:

  1. Navigasi ke portal Azure dan masuk ke portal Azure menggunakan kredensial.

  2. Dari panel kiri, pilih ID Microsoft Entra.

  3. Dari Pengguna di ID Microsoft Entra, pilih pengguna Anda.

  4. Dari halaman Profil di pengguna Microsoft Entra, salin ID Objek dan simpan di kode aplikasi Anda.

    Cuplikan layar cara menyalin ID pengguna Microsoft Entra dan menyimpannya.

Mendapatkan ID sumber daya yang tidak dapat diubah

Terkadang Anda juga perlu memberikan ID sumber daya yang tidak dapat diubah dari sumber daya Communication Service Anda. Untuk menemukannya, ikuti langkah-langkah berikut:

  1. Navigasi ke portal Azure dan masuk ke portal Azure menggunakan kredensial.
  2. Buka sumber daya Communication Service Anda.
  3. Dari panel kiri, pilih Gambaran Umum, dan beralih ke tampilan JSONCuplikan layar cara mengalihkan gambaran umum Sumber Daya Komunikasi ke tampilan JSON.
  4. Dari halaman Resource JSON , salin immutableResourceId nilai, dan berikan ke tim dukungan Anda. Cuplikan layar Resource JSON.

Verifikasi kelayakan lisensi Teams untuk menggunakan dukungan Azure Communication Services untuk pengguna Teams

Ada dua cara untuk memverifikasi kelayakan Lisensi Teams Anda untuk menggunakan dukungan Azure Communication Services untuk pengguna Teams:

  • Verifikasi melalui klien web Teams
  • Memeriksa lisensi Teams Anda saat ini melalui Microsoft Graph API

Verifikasi melalui klien web Teams

Untuk memverifikasi kelayakan Lisensi Teams Anda melalui klien web Teams, ikuti langkah-langkah berikut:

  1. Buka browser Anda dan navigasi ke klien web Teams.
  2. Masuk dengan kredensial yang memiliki lisensi Teams yang valid.
  3. Jika autentikasi berhasil dan Anda tetap berada https://teams.microsoft.com/ di domain, maka Lisensi Teams Anda memenuhi syarat. Jika autentikasi gagal atau Anda dialihkan ke https://teams.live.com/v2/ domain, maka Lisensi Teams Anda tidak memenuhi syarat untuk menggunakan dukungan Azure Communication Services untuk pengguna Teams.

Memeriksa lisensi Teams Anda saat ini melalui Microsoft Graph API

Anda dapat menemukan lisensi Teams Anda saat ini menggunakan licenseDetails Microsoft Graph API yang mengembalikan lisensi yang ditetapkan untuk pengguna. Ikuti langkah-langkah ini untuk menggunakan alat Graph Explorer untuk melihat lisensi yang ditetapkan kepada pengguna:

  1. Buka browser Anda dan navigasi ke Graph Explorer

  2. Masuk ke Graph Explorer menggunakan kredensial. Cuplikan layar cara masuk ke Graph Explorer.

  3. Dalam kotak kueri, masukkan API berikut dan klik Jalankan Kueri :

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

    Cuplikan layar cara memasukkan API di Graph Explorer.

    Atau Anda dapat mengkueri pengguna tertentu dengan memberikan ID pengguna menggunakan API berikut:

    https://graph.microsoft.com/v1.0/users/{id}/licenseDetails

  4. Panel Pratinjau respons menampilkan output sebagai berikut:

    Perhatikan bahwa objek respons yang ditampilkan di sini mungkin dipersingkat untuk keterbacaan.

    {
    "@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. Temukan detail lisensi di mana properti servicePlanName memiliki salah satu nilai dalam tabel Lisensi Teams yang Memenuhi Syarat

Memanggil kode galat SDK

SDK Azure Communication Services menggunakan kode galat berikut untuk membantu Anda memecahkan masalah panggilan. Kode kesalahan ini diekspos melalui properti call.callEndReason setelah panggilan berakhir.

Kode kesalahan Deskripsi Tindakan yang harus diambil
403 Kegagalan terlarang/autentikasi. Pastikan token Layanan Komunikasi Anda valid dan tidak kedaluwarsa.
404 Panggilan tidak ditemukan. Pastikan bahwa nomor yang Anda hubungi (atau panggilan yang Anda ikuti) ada.
408 Kontroler panggilan kehabisan waktu. Kontroler Panggilan kehabisan waktu menunggu pesan protokol dari titik akhir pengguna. Pastikan klien terhubung dan tersedia.
410 Tumpukan media lokal atau galat infrastruktur media. Pastikan Anda menggunakan SDK terbaru di lingkungan yang didukung.
430 Tak bisa menyampaikan pesan ke aplikasi klien. Pastikan aplikasi klien berjalan dan tersedia.
480 Titik akhir jarak jauh klien tidak terdaftar. Pastikan bahwa titik akhir jarak jauh tersedia.
481 Gagal menangani panggilan masuk. Ajukan permintaan dukungan melalui portal Azure.
487 Panggilan dibatalkan, ditolak secara lokal, berakhir karena masalah ketidakcocokan titik akhir, atau gagal menghasilkan penawaran media. Perilaku yang diharapkan.
490, 491, 496, 497, 498 Masalah jaringan titik akhir lokal. Periksa jaringan Anda.
500, 503, 504 Kesalahan infrastruktur Communication Services. Ajukan permintaan dukungan melalui portal Azure.
603 Panggilan ditolak secara global oleh peserta Communication Services jarak jauh Perilaku yang diharapkan.

Kode kesalahan SDK Automation Panggilan

Kode kesalahan di bawah ini diekspos oleh Call Automation SDK.

Kode Kesalahan Deskripsi Tindakan yang harus diambil
400 Permintaan Buruk Permintaan input tidak valid. Lihat pesan kesalahan untuk menentukan input mana yang salah.
400 Gagal Main Pastikan file audio Anda adalah WAV, 16KHz, Mono dan pastikan url file dapat diakses secara publik.
400 Mengenali Gagal Periksa pesan kesalahan. Pesan menyoroti apakah kegagalan ini disebabkan oleh batas waktu tercapai atau jika operasi dibatalkan. Untuk informasi selengkapnya tentang kode kesalahan dan pesan, Anda dapat memeriksa panduan cara kami untuk mengumpulkan input pengguna.
401 Tidak diizinkan Autentikasi HMAC gagal. Verifikasi apakah string koneksi yang digunakan untuk membuat CallAutomationClient sudah benar.
403 Terlarang Permintaan dilarang. Pastikan Anda dapat memiliki akses ke sumber daya yang coba Anda akses.
404 Sumber daya tidak ditemukan Panggilan yang Anda coba bertindak tidak ada. Misalnya, mentransfer panggilan yang telah terputus.
429 Terlalu banyak permintaan Coba lagi setelah penundaan yang disarankan di header Coba Lagi-Setelah, lalu backoff eksponensial.
500 Kesalahan server internal Coba lagi setelah penundaan. Jika berlanjut, ajukan tiket dukungan.
500 Gagal Main Ajukan permintaan dukungan melalui portal Azure.
500 Mengenali Gagal Periksa pesan kesalahan dan konfirmasikan format file audio valid (WAV, 16KHz, Mono), jika format file valid, maka ajukan permintaan dukungan melalui portal Azure.
502 Gateway buruk Coba lagi setelah penundaan dengan klien http baru.

Pertimbangkan tips di bawah ini saat memecahkan masalah tertentu.

  • Aplikasi Anda tidak mendapatkan peristiwa Event Grid IncomingCall: Pastikan titik akhir aplikasi telah divalidasi dengan Event Grid pada saat membuat langganan peristiwa. Status provisi untuk langganan peristiwa Anda ditandai sebagai berhasil jika validasi berhasil.
  • Mendapatkan kesalahan 'Bidang CallbackUri tidak valid': Automasi Panggilan tidak mendukung titik akhir HTTP. Pastikan url panggilan balik yang Anda berikan mendukung HTTPS.
  • Tindakan PlayAudio tidak memutar apa pun: Saat ini hanya format File gelombang (.wav) yang didukung untuk file audio. Konten audio dalam file gelombang harus mono (saluran tunggal), sampel 16-bit dengan laju pengambilan sampel 16.000 (16KHz).
  • Tindakan pada titik akhir PSTN tidak berfungsi: CreateCall, Transfer, AddParticipant dan Redirect ke nomor telepon mengharuskan Anda mengatur SourceCallerId dalam permintaan tindakan. Kecuali Anda menggunakan Perutean Langsung, ID pemanggil sumber harus menjadi nomor telepon yang dimiliki oleh sumber daya Communication Services Anda agar tindakan berhasil.

Lihat artikel ini untuk mempelajari tentang masalah yang diketahui yang dilacak oleh tim produk.

Kode galat SDK obrolan

Azure Communication Services Chat SDK menggunakan kode galat berikut untuk membantu Anda memecahkan masalah obrolan. Kode galat diekspos melalui properti error.code dalam respons kesalahan.

Kode kesalahan Deskripsi Tindakan yang harus diambil
401 Tidak diizinkan Pastikan token Layanan Komunikasi Anda valid dan tidak kedaluwarsa.
403 Terlarang Pastikan bahwa inisiator permintaan memiliki akses ke sumber daya.
429 Terlalu banyak permintaan Pastikan aplikasi pihak klien Anda menangani skenario ini dengan cara yang mudah digunakan. Jika kesalahan berlanjut, silakan ajukan permintaan dukungan.
503 Layanan Tidak Tersedia Ajukan permintaan dukungan melalui portal Azure.

Kode kesalahan SMS

SDK SMS Azure Communication Services menggunakan kode kesalahan berikut untuk membantu Anda memecahkan masalah SMS. Kode kesalahan diekspos melalui bidang "DeliveryStatusDetails" dalam laporan pengiriman SMS.

Kode kesalahan Deskripsi Tindakan yang harus diambil
2000 Pesan Berhasil Dikirim
4000 Pesan ditolak karena deteksi penipuan Pastikan Anda tidak melebihi jumlah maksimum pesan yang diizinkan untuk nomor Anda
4001 Pesan ditolak karena format angka Sumber/Dari tidak valid Pastikan nomor Kepada dalam format E.164 dan Format angka Dari dalam format E.164 atau Kode pendek
4002 Pesan ditolak karena format angka Tujuan/Ke tidak valid Pastikan nomor Ke dalam format E.164
4003 Pesan gagal dikirim karena tujuan yang tidak didukung Periksa apakah tujuan yang ingin Anda kirim didukung
4004 Pesan gagal dikirim karena Nomor Tujuan/Ke tidak ada Pastikan nomor Kepada yang Anda kirim valid
4005 Pesan diblokir oleh operator Tujuan
4006 Nomor Tujuan/Ke tidak dapat dijangkau Coba kirim ulang pesan di lain waktu
4007 Nomor Tujuan/Ke telah memilih untuk tidak menerima pesan dari Anda Tandai nomor Tujuan/Kepada sebagai ditolak sehingga tidak ada upaya pesan lebih lanjut yang dilakukan ke nomor
4008 Anda telah melebihi jumlah maksimum pesan yang diizinkan untuk profil Anda Pastikan Anda tidak melebihi jumlah maksimum pesan yang diizinkan untuk nomor Anda atau menggunakan antrean untuk membuat batch pesan
4009 Pesan ditolak oleh Microsoft Entitlement System Paling sering ini terjadi jika aktivitas penipuan terdeteksi. Silakan hubungi dukungan untuk detail selengkapnya
4010 Pesan diblokir karena nomor bebas ongkos tidak diverifikasi Tinjau batas pengiriman yang belum diverifikasi dan kirim verifikasi bebas teluk sesegera mungkin
5000 Pesan gagal dikirim. Silakan hubungi tim dukungan Microsoft untuk detail selengkapnya Mengajukan permintaan dukungan melalui portal Azure
5001 Pesan gagal dikirim karena tidak tersedianya aplikasi/sistem sementara
5002 Operator tidak mendukung laporan pengiriman Paling sering ini terjadi jika operator tidak mendukung laporan pengiriman. Tidak ada tindakan yang diperlukan karena pesan mungkin telah dikirimkan.
9999 Pesan gagal dikirim karena kesalahan/kegagalan yang tidak diketahui Coba kirim ulang pesan