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, 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
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Hinweis: Das kostenlose Testkonto können Sie nicht nutzen, wenn Sie Telefonnummern verwenden möchten. Überprüfen Sie, ob Ihr Abonnement alle Anforderungen erfüllt, wenn Sie vor dem Erstellen Ihrer Ressource Telefonnummern erwerben möchten.
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.
Geben Sie Communication in Search the Marketplace (Marketplace durchsuchen) oder in die Suchleiste oben im Portal ein.
Wählen Sie in den Ergebnissen Communication Services und anschließend Erstellen aus.
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
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Azure-Befehlszeilenschnittstelle
Das kostenlose Testkonto können Sie nicht nutzen, wenn Sie Telefonnummern verwenden möchten. Überprüfen Sie, ob Ihr Abonnement alle Anforderungen erfüllt, wenn Sie vor dem Erstellen Ihrer Ressource Telefonnummern erwerben möchten.
Erstellen einer Azure Communication Services-Ressource
Melden Sie sich zunächst bei der Azure-Befehlszeilenschnittstelle an, um eine Azure Communication Services-Ressource zu erstellen. Sie können sich beim Ausführen des az login-Befehls vom Terminal anmelden und Ihre Anmeldeinformationen bereitstellen. Führen Sie den folgenden Befehl aus, um die Ressource zu erstellen:
az communication create --name "<acsResourceName>" --location "Global" --data-location "United States" --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 create --name "<acsResourceName>" --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 anderen Befehlen finden Sie unter Azure Communication CLI.
Voraussetzungen
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Die aktuelle Version des .NET Core SDK für Ihr Betriebssystem.
- Rufen Sie die neueste Version des .NET-Identitäts-SDK ab.
- Rufen Sie die neueste Version des .NET-VerwaltungsSDK ab.
Hinweis: Das kostenlose Testkonto können Sie nicht nutzen, wenn Sie Telefonnummern verwenden möchten. Überprüfen Sie, ob Ihr Abonnement alle Anforderungen erfüllt, wenn Sie vor dem Erstellen Ihrer Ressource Telefonnummern erwerben möchten.
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:
- Melden Sie sich bei Ihrem Azure-Konto an.
- Wählen Sie auf der linken Seitenleiste die Option Abonnements aus.
- Wählen Sie das erforderliche Abonnement aus.
- Klicken Sie auf „Übersicht“.
- 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 Microsoft Entra ID.
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 Benutzer*innen zur Eingabe ihrer MSA- oder Microsoft Entra-Anmeldeinformationen aufgefordert werden.
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
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Installieren des Azure Az PowerShell-Moduls
Hinweis: Das kostenlose Testkonto können Sie nicht nutzen, wenn Sie Telefonnummern verwenden möchten. Überprüfen Sie, ob Ihr Abonnement alle Anforderungen erfüllt, wenn Sie vor dem Erstellen Ihrer Ressource Telefonnummern erwerben möchten.
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.
Zugreifen auf die Verbindungszeichenfolgen und Dienstendpunkte mit Azure CLI
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 "<acsResourceName>" --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 "<acsResourceName>" --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. Sie können Ihre Kommunikationsressource löschen, indem Sie den folgenden Befehl ausführen.
az communication delete --name "acsResourceName" --resource-group "resourceGroup"
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