快速入門 - 建立和管理通訊服務中的資源

藉由佈建您的第一個通訊服務資源，開始使用 Azure 通訊服務。 您可以透過 Azure 入口網站或使用 .NET 管理 SDK 來佈建通訊服務資源。 管理 SDK 和 Azure 入口網站可讓您使用新的部署和管理服務 Azure Resource Manager 來建立、設定、更新和刪除您的資源和介面。 SDK 中提供的所有功能都可在 Azure 入口網站中取得。

警告

請注意，您無法同時建立資源群組作為 Azure 通訊服務的資源。 建立資源之前，您必須先建立資源群組。

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。

如果您打算使用電話號碼，則無法使用免費試用帳戶。 如果您打算在建立資源之前購買電話號碼，請檢查您的訂用帳戶是否符合所有 需求。

建立 Azure 通訊服務資源

若要建立 Azure 通訊服務資源，請先登入 Azure 入口網站。 在頁面的左上角，選取 [+ 建立資源]。

在 [搜尋 Marketplace] 輸入或入口網站頂端的搜尋列中，輸入 [通訊]。

在結果中選取 [通訊服務]，再選取 [建立]。

您現在可以設定您的通訊服務資源。 在建立程序的第一個頁面上，您需要指定：

• 訂用帳戶
• 資源群組 (您可以建立新的資源群組或選擇現有的資源群組)
• 通訊服務資源的名稱
• 與資源相關聯的地理位置

在下一個步驟中，您可以將標記指派給資源。 您可以使用標記來組織 Azure 資源。 如需標記的詳細資訊，請參閱使用標記來組織 Azure 資源和管理階層。

最後，您可以檢閱您的設定，並建立資源。 部署需要數分鐘的時間才能完成。

管理您的通訊服務資源

若要管理您的通訊服務資源，請登入 Azure 入口網站，然後搜尋並選取 Azure 通訊服務。

在 [通訊服務] 頁面上，選取您的資源名稱。

資源的 [概觀] 頁面，其中包含瀏覽、停止、啟動、重新啟動和刪除等基本管理選項。 如需更多設定選項，請參閱資源頁面的左側功能表。

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• 安裝 Azure CLI

如果您打算使用電話號碼，則無法使用免費試用帳戶。 如果您打算在建立資源之前購買電話號碼，請檢查您的訂用帳戶是否符合所有 需求。

建立 Azure 通訊服務資源

若要建立 Azure 通訊服務資源，請先登入 Azure CLI。 您可以從終端機執行 az login 命令，並提供您的認證來登入。 執行下列命令來建立資源:

az communication create --name "<acsResourceName>" --location "Global" --data-location "United States" --resource-group "<resourceGroup>"

如果您想要選取特定的訂用帳戶，您也可以指定 --subscription 旗標並提供訂用帳戶識別碼。

az communication create --name "<acsResourceName>" --location "Global" --data-location "United States" --resource-group "<resourceGroup>" --subscription "<subscriptionId>"

您可以使用下列選項設定您的通訊服務資源:

• 資源群組
• 通訊服務資源的名稱
• 與資源相關聯的地理位置

在下一個步驟中，您可以將標記指派給資源。 您可以使用標記來組織 Azure 資源。 如需標記的詳細資訊，請參閱使用標記來組織 Azure 資源和管理階層。

管理您的通訊服務資源

若要將標記新增至您的通訊服務資源，請執行下列命令。 您也可以以特定訂用帳戶為目標。

az communication update --name "<communicationName>" --tags newTag="newVal1" --resource-group "<resourceGroup>"

az communication update --name "<communicationName>" --tags newTag="newVal2" --resource-group "<resourceGroup>" --subscription "<subscriptionId>"

az communication show --name "<communicationName>" --resource-group "<resourceGroup>"

az communication show --name "<communicationName>" --resource-group "<resourceGroup>" --subscription "<subscriptionId>"

如需其他命令的相關資訊，請參閱 Azure 通訊 CLI。

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• 適用於您的作業系統的最新版本 .NET Core SDK。
• 取得最新版本的 .NET 身分識別 SDK。
• 取得最新版本的 .NET 管理 SDK。

如果您打算使用電話號碼，則無法使用免費試用帳戶。 如果您打算在建立資源之前購買電話號碼，請檢查您的訂用帳戶是否符合所有 需求。

安裝 SDK

首先，將通訊服務管理 SDK 包含在您的 C# 專案中:

using Azure.ResourceManager.Communication;

訂用帳戶識別碼

您必須知道 Azure 訂用帳戶的識別碼。 可以從入口網站取得：

1. 在 Azure 入口網站上登入您的帳戶。
2. 從左邊側邊欄，選取 [訂用帳戶]。
3. 選取您要使用的訂用帳戶。
4. 按一下 [概觀]。
5. 選取您的訂用帳戶識別碼。

若要讓本快速入門中的範例能夠運作，您必須將訂用帳戶識別碼儲存在名為 AZURE_SUBSCRIPTION_ID 的環境變數中。

驗證

若要與 Azure 通訊服務通訊，您必須先向 Azure 驗證您自己。 您通常會使用服務主體身分識別來執行此動作。

選項 1: 受控識別

如果您的程式碼在 Azure 中是以服務的形式執行，則驗證的最簡單方式是從 Azure 取得受控識別。 如需詳細資訊，請參閱

• 受控識別概觀

• 支援受控識別的 Azure 服務

• 如何使用 App Service 和 Azure Functions 的受控身分識別

系統指派的受控識別

using Azure.Identity;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Communication.Models;
using System;
...
var subscriptionId = "AZURE_SUBSCRIPTION_ID";
var acsClient = new CommunicationManagementClient(subscriptionId, new ManagedIdentityCredential());

使用者指派的受控識別

您所建立受控識別的 ClientId 必須明確地傳遞給 ManagedIdentityCredential。

using Azure.Identity;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Communication.Models;
using System;
...
var subscriptionId = "AZURE_SUBSCRIPTION_ID";
var managedIdentityCredential = new ManagedIdentityCredential("AZURE_CLIENT_ID");
var acsClient = new CommunicationManagementClient(subscriptionId, managedIdentityCredential);

選項 2: 服務主體

您可能會想要使用自己管理的服務主體來向 Azure 進行驗證，而不是使用受控識別。 如需詳細資訊，請參閱在 Microsoft Entra ID 中建立和管理服務主體。

建立服務主體之後，您必須從 Azure 入口網站收集下列相關資訊：

• 用戶端識別碼
• 用戶端祕密
• 租用戶識別碼

將這些值分別儲存為名為 AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 和 AZURE_TENANT_ID 的環境變數。 接著，您可以建立通訊服務管理用戶端，如下所示：

using Azure.Identity;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Communication.Models;
using System;
...
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
var acsClient = new CommunicationManagementClient(subscriptionId, new EnvironmentCredential());

選項 3: 使用者身份識別

如果您想要代表互動使用者呼叫 Azure，而不是使用服務身分識別，您可以使用下列程式碼來建立 Azure 通訊服務管理用戶端。 這會開啟瀏覽器視窗，提示使用者輸入其 MSA 或 Microsoft Entra 認證。

using Azure.Identity;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Communication.Models;
using System;
...
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
var communicationServiceClient = new CommunicationManagementClient(subscriptionId, new InteractiveBrowserCredential());

管理通訊服務資源

與 Azure 資源互動

現在您已通過驗證，您可以使用管理用戶端來進行 API 呼叫。

針對下列每個範例，我們會將我們的通訊服務資源指派給現有的資源群組。

如果您需要建立資源群組，您可以使用 Azure 入口網站 或 Azure Resource Manager SDK 來執行此動作。

建立和管理通訊服務資源

您可以使用通訊服務管理 SDK 用戶端 (Azure.ResourceManager.Communication.CommunicationManagementClient) 的執行個體來對通訊服務資源執行作業。

建立通訊服務資源

建立通訊服務資源時，您會指定資源群組名稱和資源名稱。 Location 屬性一律是 global，而在公開預覽期間，DataLocation 值必須是 UnitedStates。

var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
var resource = new CommunicationServiceResource { Location = "Global", DataLocation = "UnitedStates"  };
var operation = await acsClient.CommunicationService.StartCreateOrUpdateAsync(resourceGroupName, resourceName, resource);
await operation.WaitForCompletionAsync();

更新通訊服務資源

...
var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
var resource = new CommunicationServiceResource { Location = "Global", DataLocation = "UnitedStates" };
resource.Tags.Add("environment","test");
resource.Tags.Add("department","tech");
// Use existing resource name and new resource object
var operation = await acsClient.CommunicationService.StartCreateOrUpdateAsync(resourceGroupName, resourceName, resource);
await operation.WaitForCompletionAsync();

列出所有通訊服務資源

var resources = acsClient.CommunicationService.ListBySubscription();
foreach (var resource in resources)
{
    Console.WriteLine(resource.Name);
}

刪除通訊服務資源

var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
await acsClient.CommunicationService.StartDeleteAsync(resourceGroupName, resourceName);

管理金鑰和連接字串

每個通訊服務資源都有一對存取金鑰和對應的連接字串。 您可以使用管理 SDK 來存取這些金鑰，然後將這些金鑰提供給其他通訊服務 SDK，以向 Azure 通訊服務驗證自己。

取得通訊服務資源的存取金鑰

var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
var keys = await acsClient.CommunicationService.ListKeysAsync(resourceGroupName, resourceName);

Console.WriteLine(keys.Value.PrimaryConnectionString);
Console.WriteLine(keys.Value.SecondaryConnectionString);

重新產生通訊服務資源的存取金鑰

var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
var keyParams = new RegenerateKeyParameters { KeyType = KeyType.Primary };
var keys = await acsClient.CommunicationService.RegenerateKeyAsync(resourceGroupName, resourceName, keyParams);

Console.WriteLine(keys.Value.PrimaryKey);

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• 安裝 Azure Az PowerShell 模組

如果您打算使用電話號碼，則無法使用免費試用帳戶。 如果您打算在建立資源之前購買電話號碼，請檢查您的訂用帳戶是否符合所有 需求。

建立 Azure 通訊服務資源

若要建立 Azure 通訊服務資源，請先登入 Azure CLI。 您可以使用 Connect-AzAccount 命令並提供您的認證，透過終端機建立資源。

首先，使用下列命令安裝 Azure 通訊服務模組 Az.Communication。

PS C:\> Install-Module Az.Communication

執行下列命令來建立資源:

PS C:\> New-AzCommunicationService -ResourceGroupName ContosoResourceProvider1 -Name ContosoAcsResource1 -DataLocation UnitedStates -Location Global

如果您想要選取特定的訂用帳戶，您也可以指定 --subscription 旗標並提供訂用帳戶識別碼。

PS C:\> New-AzCommunicationService -ResourceGroupName ContosoResourceProvider1 -Name ContosoAcsResource1 -DataLocation UnitedStates -Location Global -SubscriptionId SubscriptionID

您可以使用下列選項設定您的通訊服務資源:

• 資源群組
• 通訊服務資源的名稱
• 要與資源相關聯的地理位置

在下一個步驟中，您可以將標記指派給資源。 您可以使用標記來組織 Azure 資源。 如需詳細資訊，請參閱使用標籤來組織 Azure 資源和管理階層。

管理您的通訊服務資源

若要將標記新增至您的通訊服務資源，請執行下列命令。 您也可以以特定訂用帳戶為目標。

PS C:\> Update-AzCommunicationService -Name ContosoAcsResource1 -ResourceGroupName ContosoResourceProvider1 -Tag @{ExampleKey1="ExampleValue1"}

PS C:\> Update-AzCommunicationService -Name ContosoAcsResource1 -ResourceGroupName ContosoResourceProvider1 -Tag @{ExampleKey1="ExampleValue1"} -SubscriptionId SubscriptionID

若要列出給定訂用帳戶中的所有 Azure 通訊服務資源，請使用下列命令：

PS C:\> Get-AzCommunicationService -SubscriptionId SubscriptionID

若要列出給定資源上的所有資訊，請使用下列命令:

PS C:\> Get-AzCommunicationService -Name ContosoAcsResource1 -ResourceGroupName ContosoResourceProvider1

存取您的連接字串和服務端點

連接字串可讓通訊服務 SDK 與 Azure 連線並進行驗證。 您可以從 Azure 入口網站或以程式設計方式使用 Azure Resource Manager API，存取您的通訊服務連接字串和服務端點。

瀏覽至您的通訊服務資源之後，從導覽功能表選取 [金鑰] 並複製 連接字串 或 端點 值，供通訊服務 SDK 使用。 您可以存取主要和次要金鑰。 當您想要將您的通訊服務資源暫時存取權提供給第三方或預備環境時，這會很有用。

使用 Azure CLI 存取您的連接字串和服務端點

您也可以使用 Azure CLI 存取金鑰資訊，例如您的資源群組或特定資源的金鑰。

安裝 Azure CLI，並使用下列命令登入。 您必須提供認證，才能與 Azure 帳戶連線。

az login

現在您可以存取資源的相關重要資訊。

az communication list --resource-group "<resourceGroup>"

az communication list-key --name "<acsResourceName>" --resource-group "<resourceGroup>"

如果您想要選取特定的訂用帳戶，您也可以指定 --subscription 旗標並提供訂用帳戶識別碼。

az communication list --resource-group  "<resourceGroup>"  --subscription "<subscriptionId>"

az communication list-key --name "<acsResourceName>" --resource-group "<resourceGroup>" --subscription "<subscriptionId>"

儲存您的連接字串

通訊服務 SDK 會使用連接字串來授權對通訊服務提出的要求。 您有幾種選項可用來儲存連接字串：

• 在桌面上或裝置上執行的應用程式可將連接字串儲存在 app.config 或 web.config 檔案。 將連接字串新增至這些檔案中的 AppSettings 區段。
• 在 Azure App Service 中執行的應用程式可以將連接字串儲存在 App Service 應用程式設定中。 將連接字串新增至入口網站中 [應用程式設定] 索引標籤的 [連接字串] 區段。
• 您可以將連接字串儲存在 Azure Key Vault 中。 您可以進一步安全地管理您的連接字串。
• 如果您是在本機執行應用程式，您可能會想要將連接字串儲存在環境變數中。

將連接字串儲存在環境變數中

若要設定環境變數，請開啟主控台視窗，然後從下列索引標籤選取您的作業系統。 將 <yourconnectionstring> 用實際的連接字串取代。

Windows

開啟主控台視窗並輸入下列命令：

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<yourConnectionString>"

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。 例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。

macOS

編輯您的 .zshrc 檔案，然後新增環境變數：

export COMMUNICATION_SERVICES_CONNECTION_STRING="<yourConnectionString>"

新增環境變數之後，從主控台視窗執行 source ~/.zshrc，讓變更生效。 如果您在 IDE 開啟時建立環境變數，則必須關閉編輯器、IDE 或殼層，再重新開啟以存取該變數。

Linux

編輯您的 .bash_profile 檔案，然後新增環境變數：

export COMMUNICATION_SERVICES_CONNECTION_STRING="<yourConnectionString>"

新增環境變數之後，從主控台視窗執行 source ~/.bash_profile，讓變更生效。 如果您在 IDE 開啟時建立環境變數，則必須關閉編輯器、IDE 或殼層，再重新開啟以存取該變數。

清除資源

如果您想要清除並移除通訊服務訂用帳戶，您可以刪除資源或資源群組。 若要刪除您的通訊資源，請執行下列命令。

az communication delete --name "acsResourceName" --resource-group "resourceGroup"

刪除資源群組也會刪除與其相關聯的任何其他資源。

如果您在刪除資源時有任何指派給資源的電話號碼，則會同時自動從您的資源釋出該電話號碼。

注意

資源刪除為永久性，而且如果您刪除資源，則無法復原任何資料，包括事件方格篩選、電話號碼或其他繫結至資源的資料。

下一步

在此快速入門中，您已了解如何：

• 建立通訊服務資源
• 設定資源地理位置和標記
• 存取該資源的金鑰
• 刪除資源

建立您的第一個使用者存取權杖