Azure.ResourceManager.BotService (.NET)

SDK du plan de gestion pour provisionner et gérer les ressources Azure Bot Service via Azure Resource Manager.

Installation

dotnet add package Azure.ResourceManager.BotService
dotnet add package Azure.Identity

Versions actuelles : Stable v1.1.1, Preview v1.1.0-beta.1

Variables d'environnement

AZURE_SUBSCRIPTION_ID=<your-subscription-id>
# Pour l'authentification par principal de service (optionnel)
AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

Authentification

using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.BotService;

// S'authentifier avec DefaultAzureCredential
var credential = new DefaultAzureCredential();
ArmClient armClient = new ArmClient(credential);

// Obtenir l'abonnement et le groupe de ressources
SubscriptionResource subscription = await armClient.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup = await subscription.GetResourceGroups().GetAsync("myResourceGroup");

// Accéder à la collection de bots
BotCollection botCollection = resourceGroup.GetBots();

Hiérarchie des ressources

ArmClient
└── SubscriptionResource
    └── ResourceGroupResource
        └── BotResource
            ├── BotChannelResource (DirectLine, Teams, Slack, etc.)
            ├── BotConnectionSettingResource (Connexions OAuth)
            └── BotServicePrivateEndpointConnectionResource

Flux de travail principaux

1. Créer une ressource Bot

using Azure.ResourceManager.BotService;
using Azure.ResourceManager.BotService.Models;

// Créer les données du bot
var botData = new BotData(AzureLocation.WestUS2)
{
    Kind = BotServiceKind.Azurebot,
    Sku = new BotServiceSku(BotServiceSkuName.F0),
    Properties = new BotProperties(
        displayName: "MyBot",
        endpoint: new Uri("https://mybot.azurewebsites.net/api/messages"),
        msaAppId: "<your-msa-app-id>")
    {
        Description = "My Azure Bot",
        MsaAppType = BotMsaAppType.MultiTenant
    }
};

// Créer ou mettre à jour le bot
ArmOperation<BotResource> operation = await botCollection.CreateOrUpdateAsync(
    WaitUntil.Completed, 
    "myBotName", 
    botData);

BotResource bot = operation.Value;
Console.WriteLine($"Bot created: {bot.Data.Name}");

2. Configurer le canal DirectLine

// Obtenir le bot
BotResource bot = await resourceGroup.GetBots().GetAsync("myBotName");

// Obtenir la collection de canaux
BotChannelCollection channels = bot.GetBotChannels();

// Créer la configuration du canal DirectLine
var channelData = new BotChannelData(AzureLocation.WestUS2)
{
    Properties = new DirectLineChannel()
    {
        Properties = new DirectLineChannelProperties()
        {
            Sites = 
            {
                new DirectLineSite("Default Site")
                {
                    IsEnabled = true,
                    IsV1Enabled = false,
                    IsV3Enabled = true,
                    IsSecureSiteEnabled = true
                }
            }
        }
    }
};

// Créer ou mettre à jour le canal
ArmOperation<BotChannelResource> channelOp = await channels.CreateOrUpdateAsync(
    WaitUntil.Completed,
    BotChannelName.DirectLineChannel,
    channelData);

Console.WriteLine("DirectLine channel configured");

3. Configurer le canal Microsoft Teams

var teamsChannelData = new BotChannelData(AzureLocation.WestUS2)
{
    Properties = new MsTeamsChannel()
    {
        Properties = new MsTeamsChannelProperties()
        {
            IsEnabled = true,
            EnableCalling = false
        }
    }
};

await channels.CreateOrUpdateAsync(
    WaitUntil.Completed,
    BotChannelName.MsTeamsChannel,
    teamsChannelData);

4. Configurer le canal Web Chat

var webChatChannelData = new BotChannelData(AzureLocation.WestUS2)
{
    Properties = new WebChatChannel()
    {
        Properties = new WebChatChannelProperties()
        {
            Sites =
            {
                new WebChatSite("Default Site")
                {
                    IsEnabled = true
                }
            }
        }
    }
};

await channels.CreateOrUpdateAsync(
    WaitUntil.Completed,
    BotChannelName.WebChatChannel,
    webChatChannelData);

5. Obtenir le bot et lister les canaux

// Obtenir le bot
BotResource bot = await botCollection.GetAsync("myBotName");
Console.WriteLine($"Bot: {bot.Data.Properties.DisplayName}");
Console.WriteLine($"Endpoint: {bot.Data.Properties.Endpoint}");

// Lister les canaux
await foreach (BotChannelResource channel in bot.GetBotChannels().GetAllAsync())
{
    Console.WriteLine($"Channel: {channel.Data.Name}");
}

6. Régénérer les clés DirectLine

var regenerateRequest = new BotChannelRegenerateKeysContent(BotChannelName.DirectLineChannel)
{
    SiteName = "Default Site"
};

BotChannelResource channelWithKeys = await bot.GetBotChannelWithRegenerateKeysAsync(regenerateRequest);

7. Mettre à jour le bot

BotResource bot = await botCollection.GetAsync("myBotName");

// Mettre à jour par patch
var updateData = new BotData(bot.Data.Location)
{
    Properties = new BotProperties(
        displayName: "Updated Bot Name",
        endpoint: bot.Data.Properties.Endpoint,
        msaAppId: bot.Data.Properties.MsaAppId)
    {
        Description = "Updated description"
    }
};

await bot.UpdateAsync(updateData);

8. Supprimer le bot

BotResource bot = await botCollection.GetAsync("myBotName");
await bot.DeleteAsync(WaitUntil.Completed);

Types de canaux supportés

Référence des types clés

Valeurs BotServiceKind

Valeurs BotServiceSkuName

Valeurs BotMsaAppType

Meilleures pratiques

1. Toujours utiliser DefaultAzureCredential — prend en charge plusieurs méthodes d'authentification
2. Utiliser WaitUntil.Completed pour les opérations synchrones
3. Gérer RequestFailedException pour les erreurs API
4. Utiliser les méthodes async (*Async) pour toutes les opérations
5. Stocker les identifiants MSA App de manière sécurisée — utiliser Key Vault pour les secrets
6. Utiliser l'identité managée (BotMsaAppType.UserAssignedMSI) pour les bots en production
7. Activer les sites sécurisés pour les canaux DirectLine en production

Gestion des erreurs

using Azure;

try
{
    var operation = await botCollection.CreateOrUpdateAsync(
        WaitUntil.Completed, 
        botName, 
        botData);
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
    Console.WriteLine("Bot already exists");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}

SDK associés

Liens de référence