Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource

Führen Sie erste Schritte mit Azure Communication Services aus, indem Sie Ihre erste Communication Services-Ressource bereitstellen. Communication Services-Ressourcen können über das Azure-Portal oder mit dem .NET Management SDK bereitgestellt werden. Mithilfe des Management SDK und des Azure-Portals können Sie Ihre Ressourcen und Schnittstellen mit Azure Resource Manager, dem Bereitstellungs- und Verwaltungsdienst von Azure, erstellen, konfigurieren, aktualisieren und löschen. Alle in den SDKs verfügbaren Funktionen sind auch im Azure-Portal verfügbar.

Warnung

Beachten Sie Folgendes: Obwohl Communication Services in mehreren geografischen Regionen verfügbar sind, muss für die Ressource ein Datenspeicherort auf „US“ festgelegt sein, um eine Telefonnummer zu erhalten. Beachten Sie ferner, dass es nicht möglich ist, eine Ressourcengruppe zugleich mit einer Ressource für Azure Communication Services zu erstellen. Beim Erstellen einer Ressource muss eine bereits erstellte Ressourcengruppe verwendet werden.

Voraussetzungen

Erstellen einer Azure Communication Services-Ressource

Melden Sie sich zunächst beim Azure-Portal an, um eine Azure Communication Services-Ressource zu erstellen. Wählen Sie links oben auf der Seite die Option + Ressource erstellen aus.

Screenshot mit der hervorgehobenen Schaltfläche zum Erstellen einer Ressource im Azure-Portal

Geben Sie Communication in Search the Marketplace (Marketplace durchsuchen) oder in die Suchleiste oben im Portal ein.

Screenshot, der eine Suche nach Communication Services in der Suchleiste zeigt

Wählen Sie in den Ergebnissen Communication Services und anschließend Erstellen aus.

Screenshot: Panel Communication Services mit hervorgehobener Schaltfläche „Erstellen“.

Sie können Ihre Communication Services-Ressource jetzt konfigurieren. Auf der ersten Seite des Erstellungsprozesses werden Sie aufgefordert, Folgendes anzugeben:

  • Das Abonnement
  • Die Ressourcengruppe (Sie können eine neue Ressourcengruppe erstellen oder eine vorhandene Ressourcengruppe auswählen)
  • Den Namen der Communication Services-Ressource
  • Die Geografie, der die Ressource zugeordnet wird

Im nächsten Schritt können Sie der Ressource Tags zuweisen. Tags können verwendet werden, um Azure-Ressourcen zu organisieren. Weitere Informationen zu Tags finden Sie in der Dokumentation zum Anwenden von Tags auf Ressourcen.

Zuletzt können Sie Ihre Konfiguration überprüfen und die Ressource erstellen. Beachten Sie, dass die Bereitstellung einige Minuten dauert.

Verwalten Ihrer Communication Services-Ressource

Wechseln Sie zum Verwalten Ihrer Communication Services-Ressourcen zum Azure-Portal, und suchen Sie nach Azure Communication Services.

Wählen Sie auf der Seite Communication Services den Namen Ihrer Ressource aus.

Die Seite Übersicht für Ihre Ressource enthält Optionen für die grundlegende Verwaltung, z. B. durchsuchen, beenden, starten, neu starten und löschen. Weitere Konfigurationsoptionen finden Sie im linken Menü Ihrer Ressourcenseite.

Voraussetzungen

Erstellen einer Azure Communication Services-Ressource

Melden Sie sich zunächst bei der Azure-Befehlszeilenschnittstelle an, um eine Azure Communication Services-Ressource zu erstellen. Verwenden Sie hierzu am Terminal den az login-Befehl, und geben Sie Ihre Anmeldeinformationen ein. Führen Sie den folgenden Befehl aus, um die Ressource zu erstellen:

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

Wenn Sie ein bestimmtes Abonnement auswählen möchten, können Sie auch das --subscription-Flag und die Abonnement-ID angeben.

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

Sie können Ihre Communication Services-Ressource mit den folgenden Optionen konfigurieren:

  • Die Ressourcengruppe
  • Den Namen der Communication Services-Ressource
  • Die Geografie, der die Ressource zugeordnet wird

Im nächsten Schritt können Sie der Ressource Tags zuweisen. Tags können verwendet werden, um Azure-Ressourcen zu organisieren. Weitere Informationen zu Tags finden Sie in der Dokumentation zum Anwenden von Tags auf Ressourcen.

Verwalten Ihrer Communication Services-Ressource

Führen Sie die folgenden Befehle aus, um Tags zu Ihrer Communication Services-Ressource hinzuzufügen. Sie können auch ein bestimmtes Abonnement als Ziel haben.

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>"

Informationen zu weiteren Befehlen finden Sie unter az communication.

Voraussetzungen

Installieren des SDK

Fügen Sie zunächst die Communication Services-Verwaltungs-SDK in das C#-Projekt ein:

using Azure.ResourceManager.Communication;

Abonnement-ID

Sie müssen die ID Ihres Azure-Abonnements kennen. Diese kann über das Portal abgerufen werden:

  1. Melden Sie sich bei Ihrem Azure-Konto an.
  2. Wählen Sie auf der linken Seitenleiste die Option „Abonnements“ aus.
  3. Wählen Sie das erforderliche Abonnement aus.
  4. Klicken Sie auf „Übersicht“.
  5. Wählen Sie die ID für Ihr Abonnement aus.

In dieser Schnellstartanleitung wird davon ausgegangen, dass Sie die Abonnement-ID in einer Umgebungsvariablen mit dem Namen AZURE_SUBSCRIPTION_ID gespeichert haben.

Authentifizierung

Für die Kommunikation mit Azure Communication Services müssen Sie sich zunächst bei Azure authentifizieren. In der Regel verwenden Sie dazu eine Dienstprinzipalidentität.

Option 1: Verwaltete Identität

Wenn Ihr Code als Dienst in Azure ausgeführt wird, können Sie sich am einfachsten authentifizieren, indem Sie eine verwaltete Identität von Azure abrufen. Informieren Sie sich ausführlicher über verwaltete Identitäten.

Azure-Dienste mit Unterstützung verwalteter Identitäten

Verwenden verwalteter Identitäten für App Service und Azure Functions

Systemseitig zugewiesene verwaltete Identität

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());

Benutzerseitig zugewiesene verwaltete Identität

Die Client-ID der von Ihnen erstellten verwalteten Identität muss explizit an ManagedIdentityCredential übergeben werden.

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

Option 2: Dienstprinzipal

Anstatt eine verwaltete Identität zu verwenden, können Sie sich mithilfe eines Dienstprinzipals, den Sie selbst verwalten, bei Azure authentifizieren. Weitere Informationen finden Sie in der Dokumentation zum Erstellen und Verwalten eines Dienstprinzipals in Azure Active Directory.

Nach dem Erstellen des Dienstprinzipals müssen Sie die folgenden Informationen zu ihm über das Azure-Portal erfassen:

  • Client-ID
  • Geheimer Clientschlüssel
  • Tenant ID

Speichern Sie diese Werte in Umgebungsvariablen namens AZURE_CLIENT_ID, AZURE_CLIENT_SECRET und AZURE_TENANT_ID. Anschließend können Sie einen Communication Services-Verwaltungsclient wie den folgenden erstellen:

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());

Option 3: Benutzeridentität

Wenn Sie Azure im Namen eines interaktiven Benutzers und nicht mithilfe einer Dienstidentität aufrufen möchten, können Sie den folgenden Code verwenden, um einen Azure Communication Services-Verwaltungsclient zu erstellen. Dadurch wird ein Browserfenster geöffnet, in dem der Benutzer zur Eingabe seiner MSA- oder Azure AD-Anmeldeinformationen aufgefordert wird.

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());

Verwalten von Communication Services-Ressourcen

Interaktion mit Azure-Ressourcen

Sie haben sich authentifiziert und können nun den Verwaltungsclient für API-Aufrufe verwenden.

Für jedes der folgenden Beispiele werden die Communication Services-Ressourcen einer vorhandenen Ressourcengruppe zugewiesen.

Wenn Sie eine Ressourcengruppe erstellen müssen, können Sie dazu das Azure-Portal oder das Azure Resource Manager-SDK verwenden.

Erstellen und Verwalten einer Communication Services-Ressource

Unsere Instanz des Clients für das Communication Services-Verwaltungs-SDK (Azure.ResourceManager.Communication.CommunicationManagementClient) kann dazu verwendet werden, Vorgänge für Communication Services-Ressourcen auszuführen.

Erstellen einer Communication Services-Ressource

Beim Erstellen einer Communication Services-Ressource geben Sie den Ressourcengruppennamen und den Ressourcennamen an. Beachten Sie, dass die Eigenschaft Location immer global ist. Während der öffentlichen Vorschauphase muss UnitedStates für den Wert DataLocation angegeben werden.

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();

Aktualisieren einer Communication Services-Ressource

...
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();

Auflisten aller Communication Services-Ressourcen

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

Löschen einer Communication Services-Ressource

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

Verwalten von Schlüsseln und Verbindungszeichenfolgen

Jede Communication Services-Ressource verfügt über ein Zugriffsschlüsselpaar und zugehörige Verbindungszeichenfolgen. Auf diese Schlüssel kann mit dem Verwaltungs-SDK zugegriffen werden. Anschließend können sie dann von anderen Communication Services-SDKs verwendet werden, um sich bei Azure Communication Services zu authentifizieren.

Abrufen von Zugriffsschlüsseln für eine Communication Services-Ressource

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

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

Erneutes Generieren eines Zugriffsschlüssels für eine Communication Services-Ressource

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

Voraussetzungen

Erstellen einer Azure Communication Services-Ressource

Melden Sie sich zunächst bei der Azure-Befehlszeilenschnittstelle an, um eine Azure Communication Services-Ressource zu erstellen. Verwenden Sie hierzu am Terminal den Connect-AzAccount-Befehl, und geben Sie Ihre Anmeldeinformationen ein.

Installieren Sie zunächst unbedingt das Azure Communication Services-Modul Az.Communication mithilfe des folgenden Befehls:

PS C:\> Install-Module Az.Communication

Führen Sie den folgenden Befehl aus, um die Ressource zu erstellen:

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

Wenn Sie ein bestimmtes Abonnement auswählen möchten, können Sie auch das --subscription-Flag und die Abonnement-ID angeben.

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

Sie können Ihre Communication Services-Ressource mit den folgenden Optionen konfigurieren:

  • Die Ressourcengruppe
  • Den Namen der Communication Services-Ressource
  • Die Geografie, der die Ressource zugeordnet wird

Im nächsten Schritt können Sie der Ressource Tags zuweisen. Tags können verwendet werden, um Azure-Ressourcen zu organisieren. Weitere Informationen zu Tags finden Sie in der Dokumentation zum Anwenden von Tags auf Ressourcen.

Verwalten Ihrer Communication Services-Ressource

Führen Sie die folgenden Befehle aus, um Tags zu Ihrer Communication Services-Ressource hinzuzufügen. Sie können auch ein bestimmtes Abonnement als Ziel haben.

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

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

Verwenden Sie den folgenden Befehl, um alle Ihre Azure Communication Services-Ressourcen in einem bestimmten Abonnement aufzulisten:

PS C:\> Get-AzCommunicationService -SubscriptionId SubscriptionID

Verwenden Sie den folgenden Befehl, um alle Informationen zu einer bestimmten Ressource aufzulisten:

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

Zugreifen auf die Verbindungszeichenfolgen und Dienstendpunkte

Mit Verbindungszeichenfolgen können Communication Services-SDKs eine Verbindung mit Azure herstellen und sich bei Azure authentifizieren. Sie können auf die Communication Services-Verbindungszeichenfolgen und -Dienstendpunkte über das Azure-Portal oder programmgesteuert mit Azure Resource Manager-APIs zugreifen.

Navigieren Sie zur Communication Services-Ressource, wählen Sie im Navigationsmenü Schlüssel aus, und kopieren Sie die Werte Verbindungszeichenfolge oder Endpunkt zur Verwendung durch die Communication Services-SDKs. Beachten Sie, dass Sie Zugriff auf Primär- und Sekundärschlüssel haben. Dies kann in Szenarien nützlich sein, in denen Sie für einen Drittanbieter oder eine Stagingumgebung temporären Zugriff auf Ihre Communication Services-Ressourcen bereitstellen möchten.

Screenshot: Communication Services-Seite „Schlüssel“

Auf Schlüsselinformationen (etwa die Ressourcengruppe oder die Schlüssel für eine bestimmte Ressource) kann auch über die Azure CLI zugegriffen werden:

Installieren Sie die Azure CLI, und verwenden Sie den folgenden Befehl für die Anmeldung. Sie müssen Ihre Anmeldeinformationen eingeben, um eine Verbindung mit Ihrem Azure-Konto herzustellen.

az login

Nun können Sie auf wichtige Informationen zu Ihren Ressourcen zugreifen.

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

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

Wenn Sie ein bestimmtes Abonnement auswählen möchten, können Sie auch das Flag --subscription und die Abonnement-ID angeben.

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

az communication list-key --name "<communicationName>" --resource-group "resourceGroup>" --subscription "<subscriptionID>"

Speichern der Verbindungszeichenfolge

Communication Services-SDKs verwenden Verbindungszeichenfolgen, um an Communication Services gesendete Anforderungen zu autorisieren. Es gibt mehrere Möglichkeiten, die Verbindungszeichenfolge zu speichern:

  • Eine Anwendung, die auf dem Desktop oder auf einem Gerät ausgeführt wird, kann die Verbindungszeichenfolge in der Datei app.config oder web.config speichern. Fügen Sie die Verbindungszeichenfolge dem Abschnitt AppSettings in diesen Dateien hinzu.
  • Eine Anwendung, die in einer Azure App Service-Instanz ausgeführt wird, kann die Verbindungszeichenfolge in den App Service-Anwendungseinstellungen speichern. Fügen Sie die Verbindungszeichenfolge dem Abschnitt Verbindungszeichenfolgen auf der Registerkarte „Anwendungseinstellungen“ im Portal hinzu.
  • Sie können die Verbindungszeichenfolge in Azure Key Vault speichern.
  • Wenn Sie Ihre Anwendung lokal ausführen, können Sie die Verbindungszeichenfolge in einer Umgebungsvariablen speichern.

Speichern der Verbindungszeichenfolge in einer Umgebungsvariablen

Öffnen Sie zum Konfigurieren einer Umgebungsvariablen ein Konsolenfenster, und wählen Sie über die folgenden Registerkarten Ihr Betriebssystem aus. Ersetzen Sie <yourconnectionstring> durch Ihre Verbindungszeichenfolge.

Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<yourconnectionstring>"

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, von denen die Umgebungsvariable gelesen werden muss, z.B. das Konsolenfenster. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Wenn bei der Ressourcenlöschung der Ressource Telefonnummern zugewiesen waren, werden die Telefonnummern automatisch zum gleichen Zeitpunkt aus der Ressource freigegeben.

Hinweis

Das Löschen von Ressourcen ist endgültig, und nach dem Löschen können keine Daten wiederhergestellt werden, auch nicht Event Grid-Filter, Telefonnummern oder andere Daten, die an Ihre Ressource gebunden sind.

Nächste Schritte

In diesem Schnellstart haben Sie Folgendes gelernt:

  • Erstellen einer Communication Services-Ressource
  • Konfigurieren von Ressourcengeografie und -tags
  • Zugreifen auf die Schlüssel für diese Ressource
  • Löschen der Ressource