API Provisi Azure Communications Gateway

Artikel
05/15/2024

API Provisi Azure Communications Gateway untuk operator telekomunikasi memungkinkan Anda untuk menyediakan detail pelanggan Anda dan nomor yang ditetapkan untuk mereka ke Azure Communications Gateway (ACG). PROVISIONING API juga mendukung provisi flow-through dari beberapa layanan komunikasi backend.

Penyediaan pelanggan dan angka adalah wajib (dengan API Provisi atau Portal Manajemen Nomor berbasis browser) untuk semua kasus penggunaan kecuali untuk Operator Connect dan Telepon Teams Mobile. Untuk Operator Connect dan Telepon Teams Mobile, penggunaan API Provisi dan/atau Portal Manajemen Nomor bersifat opsional dan Anda dapat berintegrasi langsung dengan API Operator Connect sebagai gantinya.

Memulai

Prasyarat

Penyewa dengan aplikasi Azure Communications Gateway disebarkan.
Nama domain yang sepenuhnya memenuhi syarat (FQDN) untuk Azure Communications Gateway Anda yang ditampilkan di halaman Gambaran Umum untuk sumber daya di portal Azure. API tersedia di port 443 dari provapi.<base-domain>.
Komputer dengan alamat IP yang memungkinkan akses ke API, seperti yang dikonfigurasi dalam daftar izin sebagai bagian dari penyebaran Azure Communications Gateway.

Autentikasi dan Otorisasi

API Provisi menggunakan OAuth 2.0 untuk mengontrol akses ke sumber daya. Aplikasi klien harus mendapatkan token pembawa autentikasi yang valid untuk mengakses API Provisi. Token pembawa menunjukkan bahwa aplikasi diotorisasi untuk satu atau beberapa cakupan (peran) untuk API Provisi. Sebaiknya gunakan alur kredensial klien (dirancang untuk proses sisi server).

Cakupan berikut tersedia untuk PROVISIONING API:

ProvisioningAPI.Admin: Kemampuan untuk memanggil operasi apa pun di seluruh API.
ProvisioningAPI.Read: Kemampuan untuk memanggil operasi baca (GET) apa pun di seluruh API.
ProvisioningAPI.Write: Kemampuan untuk memanggil operasi tulis apa pun (PUT, PATCH) di seluruh API.
ProvisioningAPI.Delete: Kemampuan untuk memanggil operasi penghapusan (DELETE) apa pun di seluruh API.

Untuk menyiapkan alur kredensial klien:

Pastikan aplikasi Anda dapat mendukung alur kredensial klien.

Saat aplikasi Anda meminta token untuk PROVISIONING API, aplikasi tersebut harus menggunakan bidang berikut.

Parameter	Kondisi	Deskripsi
tenant	diperlukan	Penyewa direktori yang berisi Azure Communications Gateway, dalam bentuk guid atau nama domain.
scope	diperlukan	Cakupan otorisasi terhadap ID sumber daya Azure Communications Gateway. Untuk alur kredensial klien yang dijelaskan di sini, cakupannya harus `https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default`.
client_id	diperlukan	ID aplikasi (klien) yang ditetapkan ke aplikasi Anda.

roles Klaim dalam token yang diterima menentukan peran (cakupan) yang diizinkan untuk diakses oleh aplikasi klien.
Permintaan ke Platform Provisi Azure Communications Gateway harus memiliki Authorization header dengan token pembawa ini.
Lihat dokumentasi alur kredensial klien untuk contoh penggunaan token.

Gunakan portal Azure untuk mendaftarkan aplikasi di penyewa yang sama dengan penyebaran Azure Communications Gateway Anda. Lihat Mulai Cepat: Mendaftarkan aplikasi di platform identitas Microsoft - Microsoft Entra | Microsoft Learn.
Tetapkan diri Anda sebagai pemilik untuk pendaftaran aplikasi. Lihat Menetapkan pemilik aplikasi.
Konfigurasikan pendaftaran aplikasi yang dibuat dengan mendaftarkan aplikasi dengan peran aplikasi yang menggunakan cakupan untuk API Provisi, seperti yang dijelaskan sebelumnya.
- Lihat Menetapkan peran aplikasi ke aplikasi.
- API yang perlu Anda tetapkan izinnya adalah AzureCommunicationsGateway, tercantum di bawah API yang digunakan organisasi saya.
Sebagai administrator untuk penyewa, izinkan aplikasi untuk menggunakan peran aplikasi yang Anda tetapkan. Lihat Memberikan persetujuan admin.

API Provisi menggunakan rantai kepercayaan Microsoft standar untuk sertifikat keamanan.

Konsep utama

Platform Provisi memiliki tiga sumber daya utama yang dapat dikelola operator: akun, angka, dan permintaan informasi.

Sumber daya akun adalah deskripsi pelanggan operator (biasanya, perusahaan), dan pengaturan per pelanggan untuk provisi layanan.
Jumlah sumber daya milik akun. Mereka menjelaskan angka, layanan (misalnya, Perutean Langsung Microsoft Teams) yang digunakan angka, dan konfigurasi tambahan per angka.
Sumber daya Request for Information (RFI) adalah deskripsi calon pelanggan bagi operator yang menyatakan minatnya untuk menerima layanan dari operator melalui layanan backend tertentu. Saat ini hanya RPI yang dihasilkan dari Persetujuan Operator Connect dan Telepon Teams Mobile yang tersedia.

Misalnya, untuk menyediakan layanan Perutean Langsung Microsoft Teams kepada pelanggan, Contoso, buat sumber daya akun dengan API Provisi untuk Contoso. Akun berisi konfigurasi untuk Perutean Langsung (misalnya, subdomain dan token terkait, yang diperlukan untuk menyiapkan catatan DNS yang dapat digunakan Microsoft Teams untuk memvalidasi konfigurasi pelanggan). Anda kemudian harus menambahkan sumber daya nomor ke akun, dan mengaktifkan setiap nomor untuk Perutean Langsung.

Tip

Anda harus mengaktifkan layanan pada akun dan nomor dalam akun.

Memprovisikan layanan backend dengan sinkronisasi layanan backend

Azure Communications Gateway harus memiliki informasi tentang nomor yang disediakan layanan untuk menyambungkan panggilan dengan benar. Kami merekomendasikan AZURE Communications Gateway Provisioning API untuk memberikan informasi ini ke Azure Communications Gateway, tetapi Anda juga dapat menggunakan Portal Manajemen Nomor. Sebagian besar layanan backend juga perlu disediakan dengan informasi tentang angka dan akun yang akan digunakan. Persyaratan ini sering berarti bahwa beberapa proyek integrasi TI diperlukan untuk mengaktifkan layanan baru. Platform Provisi Azure Communications Gateway telah diinteegrasi sebelumnya dengan beberapa layanan backend untuk menyediakannya untuk Anda, mengurangi persyaratan integrasi TI Anda. Anda dapat menggunakan fungsi ini dengan mengaktifkan sinkronisasi layanan backend untuk layanan yang relevan. Ini juga berarti bahwa setiap integrasi TI ke platform provisi Azure Communications Gateway dapat digunakan kembali untuk layanan backend lainnya.

Misalnya Operator Connect mengamanatkan bahwa semua angka diunggah melalui OPERATOR Connect API. Jika sinkronisasi layanan backend diaktifkan untuk Operator Connect, nomor apa pun yang disediakan ke Azure Communications Gateway dan diaktifkan untuk Operator Connect akan secara otomatis disediakan ke dalam Operator Connect, yang berarti Anda tidak perlu berintegrasi dengan OPERATOR Connect API.

Provisi melalui platform provisi Azure Communications Gateway bersifat opsional untuk beberapa layanan di mana Azure Communications Gateway dapat memperoleh informasi langsung dari backend. Namun, beberapa fitur seperti penambahan header SIP pelanggan untuk tujuan penagihan tidak akan tersedia. Untuk layanan apa pun yang tidak mendukung sinkronisasi layanan backend, integrasi TI lainnya mungkin diperlukan langsung ke layanan backend. Status dukungan provisi dijelaskan dalam tabel berikut:

Layanan Backend	Persyaratan untuk menyediakan melalui Platform Provisi ACG	Provisi layanan backend didukung
Perutean Langsung	Wajib	❌
Zoom	Wajib	❌
Perlindungan Panggilan Operator Azure	Wajib	❌
Sambungan Operator	Opsional	✅
Telepon Teams Mobile	Opsional	✅

Sinkronisasi ke layanan backend tidak sinkron, yang berarti bahwa permintaan provisi Anda dapat berhasil sebelum layanan backend telah disediakan. Status ini ditandatangani dalam respons API menggunakan bidang yang serviceProvisioningStatus diatur ke pending. Kami menyarankan agar Anda meminta objek untuk memeriksa status provisinya hingga bidang ini diatur ke success. Setiap kesalahan dari penyediaan sistem backend tersedia dalam respons secara langsung.

Contoh

Contoh berikut menunjukkan contoh permintaan untuk mengelola RFIs, akun, dan angka.

Create akun yang mewakili pelanggan

Gunakan PUT pada accounts/<accountName> titik akhir untuk membuat akun bernama contoso untuk pelanggan Contoso dan mengonfigurasi satu atau beberapa layanan komunikasi untuk akun tersebut. Gunakan header If-None-Match untuk memverifikasi bahwa sumber daya akun dengan nama ini belum ada.

Lihat contoh berikut:

Perutean Langsung dikonfigurasi.
Penyaringan ID penelepon diaktifkan (default).
Subdomain untuk pelanggan adalah contoso.
Nilai TXT DNS yang disediakan pelanggan yang diperlukan untuk menyiapkan catatan DNS ada di region1Token bidang dan region2Token .

Permintaan:

PUT /accounts/contoso?api-version=2024-02-29 HTTP/1.1
{
  "name": "contoso",
  "serviceDetails": {
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1TokenValue",
          "region2Token": "region2TokenValue"
        }
      }
    }
  }
}

Respons:

{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1TokenValue",
          "region2Token": "region2TokenValue"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

Dalam contoh berikut, kami membuat akun untuk digunakan hanya dengan Teams Operator Connect, dengan sinkronisasi backend diaktifkan sehingga informasi tentang akun ini (seperti nomor apa pun yang diunggah) juga disediakan ke Teams:

Permintaan:

PUT /accounts/contoso?api-version=2024-02-29 HTTP/1.1
{
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true
    },
  }
}

Respons:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0
    }
  }
}

Menampilkan detail akun

Gunakan GET di accounts/<accountName> titik akhir untuk mendapatkan detail akun. Respons mencakup bidang berikut:

Semua konfigurasi sebelumnya diatur (atau default, jika bidang tidak diatur).
Jumlah pelanggan untuk setiap layanan yang tersedia di ACG.
Status provisi layanan backend, jika diaktifkan.
subdomainStatus, mewakili status penyediaan rekaman DNS, hanya relevan untuk Perutean Langsung.
Header ETag yang mewakili status akun saat ini. Anda dapat menggunakan nilai di header pada permintaan pembaruan berikutnya untuk memastikan Anda tidak menimpa perubahan yang If-Match dibuat oleh pengguna API lain.

Permintaan:

GET /accounts/contoso?api-version=2024-02-29 HTTP/1.1

Respons:

ETag: 12345
{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0
    },
  }
}

Permintaan yang setara jika akun memiliki beberapa layanan yang dikonfigurasi muncul sebagai berikut:

Permintaan:

GET /accounts/contoso?api-version=2024-02-29 HTTP/1.1

Respons:

ETag: 12345
{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

Memperbarui konfigurasi untuk akun

Gunakan PUT pada accounts/<accountName> titik akhir untuk memperbarui konfigurasi untuk akun. Untuk memastikan bahwa pembaruan tidak menimpa perubahan yang dilakukan oleh pengguna lain, tambahkan If-Match header dengan ETag dari respons terbaru untuk akun tersebut.

Permintaan:

PUT /accounts/contoso?api-version=2024-02-29 HTTP/1.1
ETag: 12345
{
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": false,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

Respons:

ETag: 56789
{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": false,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

Menambahkan satu nomor ke akun

Gunakan PUT pada account/<accountName>/numbers/<telephoneNumber> titik akhir untuk menambahkan angka ke akun, mengaktifkan satu atau beberapa layanan komunikasi dan menambahkan konfigurasi lainnya. Layanan komunikasi yang dipilih juga harus dikonfigurasi pada akun. Gunakan header If-None-Match untuk memverifikasi bahwa sumber daya angka dengan nomor ini belum ada. Semua angka harus dibuat dalam format E.164.

Lihat contoh berikut:

Angkanya adalah +123451.
Koneksi operator diaktifkan.
Konfigurasi yang diperlukan untuk mengunggah nomor ke Operator Connect disediakan
customSipHeader menentukan bahwa Azure Communications Gateway harus menambahkan header dengan nilai exampleHeaderContents ke pesan yang dikirim ke jaringan operator. Nama header diatur sebagai bagian dari penyebaran Azure Communications Gateway.
Bidang serviceProvisioningStatus dalam respons memperlihatkan status sinkronisasi ke layanan backend.

PUT /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Respons:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Memeriksa status provisi setelah beberapa waktu

Gunakan GET pada account/<accountName>/numbers/<telephoneNumber> setelah tindakan provisi untuk memeriksa status nomor. Jika angka berhasil disediakan, bidang diperbarui serviceProvisioningStatus dari pending ke synced.

Permintaan:

GET /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1

Respons:

{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Kesalahan dalam provisi layanan backend untuk mengunggah angka

Dalam contoh ini, provisi backend saat mengunggah angka mencapai kesalahan, yang tercermin kembali pada respons. Pesan kesalahan diteruskan secara transparan dari layanan backend.

Catatan

Awalnya ketika menyediakan angka yang memiliki pending status, yang perlu dikueri lagi untuk mengonfirmasi keberhasilan/kegagalan.

Permintaan asli, yang kehilangan nilai untuk usage bidang :

PUT /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Respons dari kueri GET setelah beberapa waktu:

{  
  "serviceProvisioningStatus": "failed",
  "serviceProvisioningErrors": [
    {
      "code": "InvalidRequest",
      "message": "Invalid/missing required configuration attributes: Usage",
      "target": "oc",
    }
  ],
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }

Memperbarui konfigurasi untuk angka

Gunakan PUT pada account/<accountName>/numbers/<telephoneNumber> titik akhir untuk memperbarui konfigurasi untuk angka. Untuk memastikan bahwa pembaruan tidak menimpa perubahan yang dilakukan oleh pengguna lain, tambahkan header If-Match dengan ETag dari respons terbaru untuk angka tersebut.

Permintaan:

PUT /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
ETag: 123
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling",
          "Mobile"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Respons:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling",
          "Mobile"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Mencantumkan Permintaan Informasi

Gunakan GET di /teamsRequestsForInformation titik akhir untuk mendapatkan daftar persetujuan Teams yang telah dikirimkan kepada Anda oleh calon pelanggan.

Permintaan:

GET /teamsRequestsForInformation?api-version=2024-02-29 HTTP/1.1

Respons:

{
  "value": [
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "id": "contoso",
      "tenantId": "contosoTenantId",
      "accountName": "contoso",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name",
          "email": "example@contoso.com",
          "telephoneNumber": "+1234567890",
          "companyName": "contoso",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "example status",
        "lastModifiedOn": "2024-05-07T11:15:10.520Z",
        "comment": "example comment"
      }
    },
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "id": "contoso2",
      "tenantId": "contosoTenantId2",
      "accountName": "contoso2",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name2",
          "email": "example@contoso2.com",
          "telephoneNumber": "+1234567891",
          "companyName": "contoso2",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "example status",
        "lastModifiedOn": "2024-05-07T11:15:10.520Z",
        "comment": "example comment"
      }
    },
    ... // more RFIs
  ],
  "nextLink": "string"
}

Memperbarui Permintaan Informasi

Gunakan PATCH pada /teamsRequestsForInformation/<tenantID> titik akhir untuk memperbarui status RFI, yang tercermin dalam layanan backend. Operator Connect dan Telepon Teams Mobile memungkinkan Anda untuk menunjukkan status permintaan kembali ke pelanggan akhir sehingga status yang diperbarui muncul di Teams Admin Center pelanggan.

Minta

PATCH /teamsRequestsForInformation/contosoTenantId
{
  "customerRelationship": {
    "status": "new status",
    "comment": "new comment"
  }
}

Respons

{
    {
      "serviceProvisioningStatus": "pending",
      "serviceProvisioningErrors": null,
      "id": "contoso",
      "tenantId": "contosoTenantId",
      "accountName": "contoso",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name",
          "email": "example@contoso.com",
          "telephoneNumber": "+1234567890",
          "companyName": "contoso",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "new status",
        "lastModifiedOn": "2024-05-07T12:15:10.520Z",
        "comment": "new comment"
      }
    }
}

Mencantumkan semua nomor yang ditetapkan ke akun

Gunakan permintaan GET pada /accounts/<accountName>/numbers titik akhir untuk mendapatkan daftar angka yang telah disediakan untuk akun tersebut.

Permintaan:

GET /accounts/contoso/numbers?api-version=2024-02-29 HTTP/1.1

Respons untuk akun hanya dengan nomor Operator Connect:

{
  "value": [
    {
      "serviceProvisioningStatus": "pending",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123451",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsOperatorConnect": {
          "enabled": true,
          "assignmentStatus": "assigned",
          "configuration": {
            "usage": "CallingUserAssignment",
            "choosableCapabilities": [
              "InboundCalling",
              "OutboundCalling",
              "Mobile"
            ],
            "civicAddressId": "civicAddressIdString",
            "allowTenantAddressUpdate": true,
          }
        },
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    ... // more OC numbers
  ],
  nextLink: "string"
}

Respons untuk akun dengan nomor Operator Connect dan Perutean Langsung yang disediakan:

{
  "value": [
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123451",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsOperatorConnect": {
          "enabled": true,
          "assignmentStatus": "assigned",
          "configuration": {
            "usage": "CallingUserAssignment",
            "choosableCapabilities": [
              "InboundCalling",
              "OutboundCalling",
              "Mobile"
            ],
            "civicAddressId": "civicAddressIdString",
            "allowTenantAddressUpdate": true,
          }
        },
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123452",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsDirectRouting": {
          "enabled": true
        }
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    ... // more DR and OC numbers
  ],
  nextLink: "string"
}

Mencantumkan semua lokasi darurat untuk akun tertentu

Gunakan permintaan GET di /accounts/<accountName>/teamsCivicAddresses titik akhir untuk mendapatkan daftar lengkap Alamat Civic yang dikonfigurasi di Teams Admin Center untuk akun tersebut. Anda dapat menggunakan populasi daftar ini sebagai locationid saat membuat atau memperbarui angka dalam akun.

Permintaan:

GET /accounts/contoso/teamsCivicAddresses?api-version=2024-02-29 HTTP/1.1

Respons:

{
  "value": [
    {
      "id": "string",
      "country": "string",
      "houseNumber": "string",
      "houseNumberSuffix": "string",
      "preDirectional": "string",
      "streetName": "string",
      "streetSuffix": "string",
      "postDirectional": "string",
      "stateOrProvince": "string",
      "countyOrDistrict": "string",
      "cityOrTown": "string",
      "cityOrTownAlias": "string",
      "postalOrZipCode": "string",
      "description": "string",
      "companyName": "string",
      "companyId": "string",
      "defaultLocationId": "string",
      "validationStatus": "notValidated",
      "tenantId": "string",
      "partnerId": "string",
      "locations": [
        {
          "id": "string",
          "civicAddressId": "string",
          "description": "string",
          "additionalInfo": "string",
          "isDefault": true,
          "elin": "string"
        }
      ],
      "latitude": "string",
      "longitude": "string"
    },
    ... // more locations
  ],
  "nextLink": "string"
}

Menghapus nomor dari akun

Gunakan DELETE pada /accounts/<accountName>/numbers/<telephoneNumber> titik akhir untuk merilis angka dari penyewa. Operasi ini akan menghapus penetapan angka dari pengguna jika ditetapkan lalu melepaskan nomor dari penyewa.

Permintaan:

DELETE /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1

Respons:

204 Status Code

Pemecahan Masalah

Perutean Langsung Teams tidak berfungsi untuk nomor di akun.
- Periksa token DNS telah divalidasi dengan mengirim GET di akun, memverifikasi bahwa serviceDetails.teamsDirectRouting memiliki subdomainStatus sama dengan Provisioned.
Saya telah mengonfigurasi angka untuk menggunakan Perutean/Zoom Langsung, tetapi tampaknya tidak berfungsi.
- Periksa apakah akun telah dikonfigurasi untuk menggunakan Perutean/Zoom Langsung, dan nomor tersebut mengaktifkan fitur khusus ini.
Saya telah berhasil menghubungi API, tetapi setelah membuat beberapa permintaan, koneksi saya mulai kehabisan waktu.
- API provisi dibatasi tarif (dengan tarif per detik yang wajar). Beri ruang pada permintaan Anda, atau gunakan titik akhir batch, untuk menghindari pembatasan tarif. Batas tarif habis pada akhirnya, dan Anda akan dapat terhubung.

Langkah berikutnya

Mulai mengintegrasikan dengan API Provisi Azure Communications Gateway.

Bagikan melalui

API Provisi Azure Communications Gateway

Memulai

Prasyarat

Autentikasi dan Otorisasi

Konsep utama

Memprovisikan layanan backend dengan sinkronisasi layanan backend

Contoh

Create akun yang mewakili pelanggan

Menampilkan detail akun

Memperbarui konfigurasi untuk akun

Menambahkan satu nomor ke akun

Memeriksa status provisi setelah beberapa waktu

Kesalahan dalam provisi layanan backend untuk mengunggah angka

Memperbarui konfigurasi untuk angka

Mencantumkan Permintaan Informasi

Memperbarui Permintaan Informasi

Mencantumkan semua nomor yang ditetapkan ke akun

Mencantumkan semua lokasi darurat untuk akun tertentu

Menghapus nomor dari akun

Pemecahan Masalah

Langkah berikutnya

Sumber Daya Tambahan: