Implémenter une compétence

S'APPLIQUE À : SDK v4

Vous pouvez utiliser des compétences pour étendre un autre bot. Une compétence est un bot qui peut effectuer un ensemble de tâches pour un autre bot.

• L’interface d’une compétence est décrite par un manifeste. Les développeurs qui n’ont pas accès au code source de la compétence peuvent utiliser les informations du manifeste pour concevoir leur consommateur de compétences.
• Une compétence peut utiliser la validation des revendications pour gérer les bots ou les utilisateurs qui peuvent y accéder.

Cet article montre comment implémenter une compétence qui répercute l’entrée de l’utilisateur.

Certains types de consommateurs de compétences ne peuvent pas utiliser certains types de bots de compétence. Le tableau suivant décrit les combinaisons prises en charge.

	Compétence multilocataire	Compétence monolocataire	Compétence en matière d'identité managée affectée par l'utilisateur
Consommateur multilocataire	Prise en charge	Non pris en charge	Non pris en charge
Consommateur d'un locataire unique	Non pris en charge	Pris en charge, si les deux applications appartiennent au même locataire	Pris en charge, si les deux applications appartiennent au même locataire
Consommateur d'identité managée affectée par l'utilisateur	Non pris en charge	Pris en charge, si les deux applications appartiennent au même locataire	Pris en charge, si les deux applications appartiennent au même locataire

Remarque

Les kits de développement logiciel (SDK) JavaScript, C# et Python bot Framework continueront d'être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023. Seuls les correctifs de sécurité critiques et de bogues dans ce référentiel seront appliqués.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront à fonctionner.

Pour la nouvelle version de bot, envisagez d'utiliser Power Virtual Agents et découvrez comment choisir la solution de bot conversationnel appropriée.

Pour plus d'informations, consultez Les futures versions de bot.

Prérequis

• Connaissances des concepts de base des bots et des compétences.
• Un abonnement Azure (pour déployer votre compétence). Si vous n’en avez pas, créez un compte gratuit avant de commencer.
• Une copie de l'échantillon des compétences bot-à-bot simple en C#, JavaScript, Java, ou Python.

Remarque

À compter de la version 4.11, vous n'avez pas besoin d'un ID d'application et d'un mot de passe pour tester une compétence localement dans le Bot Framework Emulator. Un abonnement Azure est toujours nécessaire pour déployer votre compétence sur Azure.

À propos de cet exemple

L’exemple de bot-à-bot simple de compétences comprend des projets pour deux bots :

• Bot de compétences echo, qui implémente la compétence.
• Bot racine simple, qui implémente un bot racine qui consomme la compétence.

Cet article se concentre sur la compétence, qui comprend la logique de prise en charge dans son bot et son adaptateur.

C#

JavaScript

Java

Python

Pour plus d’informations sur le bot racine simple, découvrez comment implémenter un consommateur de compétences.

Ressources

Pour les bots déployés, l'authentification entre bots exige que chaque bot participant ait une identité valide. Toutefois, vous pouvez tester les compétences multilocataires et les consommateurs de compétences localement avec l'émulateur sans ID d'application et mot de passe.

Pour mettre la compétence à la disposition des bots en contact avec l'utilisateur, enregistrez la compétence auprès d'Azure. Pour plus d'informations, découvrez comment inscrire un bot auprès d'Azure AI Bot Service.

Configuration de l’application

Vous pouvez également ajouter les informations relatives à l'identité de la compétence à son fichier de configuration. Si la compétence ou le consommateur de compétences fournit des informations d'identité, les deux le doivent.

Le groupe d’appelants autorisés peut limiter les consommateurs de compétences pouvant accéder à la compétence. Ajoutez un élément « * » pour accepter les appels de n'importe quel consommateur de compétences.

Remarque

Si vous testez votre compétence localement sans informations d'identité de bot, ni la compétence ni le consommateur de compétences n'exécutent le code pour effectuer la validation des revendications.

C#

EchoSkillBot\appsettings.json

Vous pouvez également ajouter les informations relatives à l'identité de la compétence au fichier .env.

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",

  // This is a comma separate list with the App IDs that will have access to the skill.
  // This setting is used in AllowedCallersClaimsValidator.
  // Examples: 
  //    [ "*" ] allows all callers.
  //    [ "AppId1", "AppId2" ] only allows access to parent bots with "AppId1" and "AppId2".
  "AllowedCallers": [ "*" ]
}

JavaScript

echo-skill-bot/.env

Vous pouvez également ajouter les informations relatives à l'identité de la compétence au fichier .env.

MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
AllowedCallers=*

Java

DialogSkillBot\resources\application.properties

Si vous le souhaitez, ajoutez l'identifiant et le mot de passe de l'ID d'application au fichier application.properties.

MicrosoftAppId=
MicrosoftAppPassword=
server.port=39783
# This is a comma separate list with the App IDs that will have access to the skill.
# This setting is used in AllowedCallersClaimsValidator.
# Examples:
#    * allows all callers.
#    AppId1,AppId2 only allows access to parent bots with "AppId1" and "AppId2".
AllowedCallers=*

Python

Si vous le souhaitez, ajoutez l'identifiant et le mot de passe de l'ID d'application au fichier config.py.

config.py

APP_ID = os.environ.get(
    "MicrosoftAppId", ""
)
APP_PASSWORD = os.environ.get(
    "MicrosoftAppPassword", ""
)

Logique du gestionnaire d’activités

Pour accepter les paramètres d’entrée

Le consommateur de compétences peut envoyer des informations à la compétence. Une façon d’accepter ces informations consiste à les accepter via la propriété value sur les messages entrants. Une autre méthode consiste à gérer les activités d’événement et d’appel.

La compétence de cet exemple n'accepte pas les paramètres d'entrée.

Pour continuer ou terminer une conversation

Quand la compétence envoie une activité, le consommateur de compétences doit transférer l’activité à l’utilisateur.

Toutefois, vous devez envoyer une activité endOfConversation lorsque la compétence se termine ; sinon, le consommateur de compétences continue de transférer les activités de l’utilisateur à la compétence. Si vous le souhaitez, utilisez la propriété value de l’activité pour inclure une valeur de retour, puis utilisez la propriété code de l’activité pour indiquer pourquoi la compétence se termine.

C#

EchoSkillBot\Bots\EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    if (turnContext.Activity.Text.Contains("end") || turnContext.Activity.Text.Contains("stop"))
    {
        // Send End of conversation at the end.
        var messageText = $"ending conversation from the skill...";
        await turnContext.SendActivityAsync(MessageFactory.Text(messageText, messageText, InputHints.IgnoringInput), cancellationToken);
        var endOfConversation = Activity.CreateEndOfConversationActivity();
        endOfConversation.Code = EndOfConversationCodes.CompletedSuccessfully;
        await turnContext.SendActivityAsync(endOfConversation, cancellationToken);
    }
    else
    {
        var messageText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(messageText, messageText, InputHints.IgnoringInput), cancellationToken);
        messageText = "Say \"end\" or \"stop\" and I'll end the conversation and back to the parent.";
        await turnContext.SendActivityAsync(MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput), cancellationToken);
    }
}

JavaScript

echo-skill-bot/bot.js

this.onMessage(async (context, next) => {
    switch (context.activity.text.toLowerCase()) {
    case 'end':
    case 'stop':
        await context.sendActivity({
            type: ActivityTypes.EndOfConversation,
            code: EndOfConversationCodes.CompletedSuccessfully
        });
        break;
    default:
        await context.sendActivity(`Echo (JS) : '${ context.activity.text }'`);
        await context.sendActivity('Say "end" or "stop" and I\'ll end the conversation and back to the parent.');
    }

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

echoSkillBot\EchoBot.java

protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    if (
        turnContext.getActivity().getText().contains("end") || turnContext.getActivity().getText().contains("stop")
    ) {
        String messageText = "ending conversation from the skill...";
        return turnContext.sendActivity(MessageFactory.text(messageText, messageText, InputHints.IGNORING_INPUT))
            .thenApply(result -> {
                Activity endOfConversation = Activity.createEndOfConversationActivity();
                endOfConversation.setCode(EndOfConversationCodes.COMPLETED_SUCCESSFULLY);
                return turnContext.sendActivity(endOfConversation);
            })
            .thenApply(finalResult -> null);
    } else {
        String messageText = String.format("Echo: %s", turnContext.getActivity().getText());
        return turnContext.sendActivity(MessageFactory.text(messageText, messageText, InputHints.IGNORING_INPUT))
            .thenApply(result -> {
                String nextMessageText =
                    "Say \"end\" or \"stop\" and I'll end the conversation and back to the parent.";
                return turnContext.sendActivity(
                    MessageFactory.text(nextMessageText, nextMessageText, InputHints.EXPECTING_INPUT)
                );
            })
            .thenApply(result -> null);
    }
}

Python

echo-skill-bot/bots/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    if "end" in turn_context.activity.text or "stop" in turn_context.activity.text:
        # Send End of conversation at the end.
        await turn_context.send_activity(
            MessageFactory.text("Ending conversation from the skill...")
        )

        end_of_conversation = Activity(type=ActivityTypes.end_of_conversation)
        end_of_conversation.code = EndOfConversationCodes.completed_successfully
        await turn_context.send_activity(end_of_conversation)
    else:
        await turn_context.send_activity(
            MessageFactory.text(f"Echo (python): {turn_context.activity.text}")
        )
        await turn_context.send_activity(
            MessageFactory.text(
                f'Say "end" or "stop" and I\'ll end the conversation and back to the parent.'
            )
        )

Pour annuler la compétence

Pour les compétences multitours, vous pouvez aussi accepter les activités endOfConversation d’un consommateur de compétences pour permettre à celui-ci d’annuler la conversation en cours.

La logique de cette compétence ne change pas d'un tour à l'autre. Si vous implémentez une compétence qui alloue des ressources de conversation, ajoutez le code de nettoyage des ressources au gestionnaire de fin de conversation.

C#

EchoSkillBot\Bots\EchoBot.cs

protected override Task OnEndOfConversationActivityAsync(ITurnContext<IEndOfConversationActivity> turnContext, CancellationToken cancellationToken)
{
    // This will be called if the root bot is ending the conversation.  Sending additional messages should be
    // avoided as the conversation may have been deleted.
    // Perform cleanup of resources if needed.
    return Task.CompletedTask;
}

JavaScript

echo-skill-bot/bot.js

Utilisez la méthode onUnrecognizedActivityType pour ajouter une logique de fin de conversation. Dans le gestionnaire, vérifiez si le type de l’activité non reconnue correspond à endOfConversation.

this.onEndOfConversation(async (context, next) => {
    // This will be called if the root bot is ending the conversation.  Sending additional messages should be
    // avoided as the conversation may have been deleted.
    // Perform cleanup of resources if needed.

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

echoSkillBot\EchoBot.java

protected CompletableFuture<Void> onEndOfConversationActivity(TurnContext turnContext) {
    // This will be called if the root bot is ending the conversation. Sending
    // additional messages should be
    // avoided as the conversation may have been deleted.
    // Perform cleanup of resources if needed.
    return CompletableFuture.completedFuture(null);
}

Python

echo-skill-bot/bots/echo_bot.py

async def on_end_of_conversation_activity(self, turn_context: TurnContext):
    # This will be called if the root bot is ending the conversation.  Sending additional messages should be
    # avoided as the conversation may have been deleted.
    # Perform cleanup of resources if needed.
    pass

Validateur de revendications

Cet exemple utilise une liste d’appelants autorisés pour la validation des revendications. La liste est définie dans le fichier de configuration de la compétence et est lue dans l’objet validateur lors de sa création.

Vous devez ajouter un validateur de revendications à la configuration de l'authentification. Les revendications sont évaluées après l’en-tête d’authentification. Votre code de validation doit lever une erreur ou une exception pour refuser la demande. Nombreuses sont les raisons pour lesquelles vous pouvez souhaiter refuser une demande authentifiée autrement. Par exemple :

• La compétence fait partie d’un service payant. L'utilisateur ne figurant pas dans la base de données ne doit pas y avoir accès.
• La compétence est privée. Seuls certains consommateurs de compétences peuvent appeler la compétence.

Important

Si vous ne fournissez pas de validateur de revendications, votre bot génère une erreur ou une exception lors de la réception d'une activité du consommateur de compétences.

C#

Le kit de développement logiciel (SDK) fournit une classe AllowedCallersClaimsValidator qui ajoute une autorisation au niveau de l'application en fonction d'une liste simple d'ID des applications autorisées à appeler la compétence. Si la liste contient un astérisque (*), tous les appelants sont autorisés. Le validateur de revendications est configuré dans Startup.cs.

JavaScript

Le kit de développement logiciel (SDK) fournit une classe allowedCallersClaimsValidator qui ajoute une autorisation au niveau de l'application en fonction d'une liste simple d'ID des applications autorisées à appeler la compétence. Si la liste contient un astérisque (*), tous les appelants sont autorisés. Le validateur de revendications est configuré dans index.js.

Java

Le kit de développement logiciel (SDK) fournit une classe AllowedCallersClaimsValidator qui ajoute une autorisation au niveau de l'application en fonction d'une liste simple d'ID des applications autorisées à appeler la compétence. Si la liste contient un astérisque (*), tous les appelants sont autorisés. Le validateur de revendications est configuré dans Application.java.

Python

Définissez une méthode de validation de revendications qui génère une erreur pour refuser une demande entrante.

echo-skill-bot/authentication/allowed_callers_claims_validator.py

class AllowedCallersClaimsValidator:

    config_key = "ALLOWED_CALLERS"

    def __init__(self, config: DefaultConfig):
        if not config:
            raise TypeError(
                "AllowedCallersClaimsValidator: config object cannot be None."
            )

        # ALLOWED_CALLERS is the setting in config.py file
        # that consists of the list of parent bot ids that are allowed to access the skill
        # to add a new parent bot simply go to the AllowedCallers and add
        # the parent bot's microsoft app id to the list
        caller_list = getattr(config, self.config_key)
        if caller_list is None:
            raise TypeError(f'"{self.config_key}" not found in configuration.')
        self._allowed_callers = frozenset(caller_list)

    @property
    def claims_validator(self) -> Callable[[List[Dict]], Awaitable]:
        async def allow_callers_claims_validator(claims: Dict[str, object]):
            # if allowed_callers is None we allow all calls
            if "*" not in self._allowed_callers and SkillValidation.is_skill_claim(
                claims
            ):
                # Check that the appId claim in the skill request is in the list of skills configured for this bot.
                app_id = JwtTokenValidation.get_app_id_from_claims(claims)
                if app_id not in self._allowed_callers:
                    raise PermissionError(
                        f'Received a request from a bot with an app ID of "{app_id}".'
                        f" To enable requests from this caller, add the app ID to your configuration file."
                    )

            return

        return allow_callers_claims_validator

Adaptateur de compétences

Lorsqu’une erreur se produit, l’adaptateur de la compétence doit effacer l’état de la conversation de la compétence et doit aussi envoyer une activité endOfConversation au consommateur de compétences. Utilisez la propriété code de l’activité pour signaler que la compétence s’est terminée en raison d’une erreur.

C#

EchoSkillBot\SkillAdapterWithErrorHandler.cs

private async Task HandleTurnError(ITurnContext turnContext, Exception exception)
{
    // Log any leaked exception from the application.
    _logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

    await SendErrorMessageAsync(turnContext, exception);
    await SendEoCToParentAsync(turnContext, exception);
}

private async Task SendErrorMessageAsync(ITurnContext turnContext, Exception exception)
{
    try
    {
        // Send a message to the user.
        var errorMessageText = "The skill encountered an error or bug.";
        var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
        await turnContext.SendActivityAsync(errorMessage);

        errorMessageText = "To continue to run this bot, please fix the bot source code.";
        errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
        await turnContext.SendActivityAsync(errorMessage);

        // Send a trace activity, which will be displayed in the Bot Framework Emulator.
        // Note: we return the entire exception in the value property to help the developer;
        // this should not be done in production.
        await turnContext.TraceActivityAsync("OnTurnError Trace", exception.ToString(), "https://www.botframework.com/schemas/error", "TurnError");
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught in SendErrorMessageAsync : {ex}");
    }
}

private async Task SendEoCToParentAsync(ITurnContext turnContext, Exception exception)
{
    try
    {
        // Send an EndOfConversation activity to the skill caller with the error to end the conversation,
        // and let the caller decide what to do.
        var endOfConversation = Activity.CreateEndOfConversationActivity();
        endOfConversation.Code = "SkillError";
        endOfConversation.Text = exception.Message;
        await turnContext.SendActivityAsync(endOfConversation);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught in SendEoCToParentAsync : {ex}");
    }
}

JavaScript

echo-skill-bot/index.js

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to the console log, instead of to app insights.
    // NOTE: In a production environment, you should consider logging this to Azure
    //       application insights.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

    await sendErrorMessage(context, error);
    await sendEoCToParent(context, error);
};

async function sendErrorMessage(context, error) {
    try {
        // Send a message to the user.
        let onTurnErrorMessage = 'The skill encountered an error or bug.';
        await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);

        onTurnErrorMessage = 'To continue to run this bot, please fix the bot source code.';
        await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);

        // Send a trace activity, which will be displayed in the Bot Framework Emulator.
        // Note: we return the entire exception in the value property to help the developer;
        // this should not be done in production.
        await context.sendTraceActivity('OnTurnError Trace', error.toString(), 'https://www.botframework.com/schemas/error', 'TurnError');
    } catch (err) {
        console.error(`\n [onTurnError] Exception caught in sendErrorMessage: ${ err }`);
    }
}

async function sendEoCToParent(context, error) {
    try {
        // Send an EndOfConversation activity to the skill caller with the error to end the conversation,
        // and let the caller decide what to do.
        const endOfConversation = {
            type: ActivityTypes.EndOfConversation,
            code: 'SkillError',
            text: error.toString()
        };
        await context.sendActivity(endOfConversation);
    } catch (err) {
        console.error(`\n [onTurnError] Exception caught in sendEoCToParent: ${ err }`);
    }
}

Java

echoSkillBot\SkillAdapterWithErrorHandler.java

public SkillAdapterWithErrorHandler(
    Configuration configuration,
    AuthenticationConfiguration authenticationConfiguration
) {
    super(configuration, authenticationConfiguration);
    setOnTurnError(new SkillAdapterErrorHandler());
}

private class SkillAdapterErrorHandler implements OnTurnErrorHandler {

    @Override
    public CompletableFuture<Void> invoke(TurnContext turnContext, Throwable exception) {
        return sendErrorMessage(turnContext, exception).thenAccept(result -> {
            sendEoCToParent(turnContext, exception);
        });
    }

    private CompletableFuture<Void> sendErrorMessage(TurnContext turnContext, Throwable exception) {
        try {
            // Send a message to the user.
            String errorMessageText = "The skill encountered an error or bug.";
            Activity errorMessage =
                MessageFactory.text(errorMessageText, errorMessageText, InputHints.IGNORING_INPUT);
            return turnContext.sendActivity(errorMessage).thenAccept(result -> {
                String secondLineMessageText = "To continue to run this bot, please fix the bot source code.";
                Activity secondErrorMessage =
                    MessageFactory.text(secondLineMessageText, secondLineMessageText, InputHints.EXPECTING_INPUT);
                turnContext.sendActivity(secondErrorMessage)
                    .thenApply(
                        sendResult -> {
                            // Send a trace activity, which will be displayed in the Bot Framework Emulator.
                            // Note: we return the entire exception in the value property to help the
                            // developer;
                            // this should not be done in production.
                            return TurnContext.traceActivity(
                                turnContext,
                                String.format("OnTurnError Trace %s", exception.toString())
                            );

                        }
                    );
            });
        } catch (Exception ex) {
            return Async.completeExceptionally(ex);
        }
    }

    private CompletableFuture<Void> sendEoCToParent(TurnContext turnContext, Throwable exception) {
        try {
            // Send an EndOfConversation activity to the skill caller with the error to end
            // the conversation,
            // and let the caller decide what to do.
            Activity endOfConversation = Activity.createEndOfConversationActivity();
            endOfConversation.setCode(EndOfConversationCodes.SKILL_ERROR);
            endOfConversation.setText(exception.getMessage());
            return turnContext.sendActivity(endOfConversation).thenApply(result -> null);
        } catch (Exception ex) {
            return Async.completeExceptionally(ex);
        }
    }

}

Python

echo-skill-bot/adapter_with_error_handler.py

    # This check writes out errors to console log
    # NOTE: In production environment, you should consider logging this to Azure
    #       application insights.
    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
    traceback.print_exc()
    await self._send_error_message(turn_context, error)
    await self._send_eoc_to_parent(turn_context, error)

async def _send_error_message(self, turn_context: TurnContext, error: Exception):
    try:
        # Send a message to the user.
        error_message_text = "The skill encountered an error or bug."
        error_message = MessageFactory.text(
            error_message_text, error_message_text, InputHints.ignoring_input
        )
        await turn_context.send_activity(error_message)

        error_message_text = (
            "To continue to run this bot, please fix the bot source code."
        )
        error_message = MessageFactory.text(
            error_message_text, error_message_text, InputHints.ignoring_input
        )
        await turn_context.send_activity(error_message)

        # Send a trace activity, which will be displayed in Bot Framework Emulator.
        await turn_context.send_trace_activity(
            label="TurnError",
            name="on_turn_error Trace",
            value=f"{error}",
            value_type="https://www.botframework.com/schemas/error",
        )
    except Exception as exception:
        print(
            f"\n Exception caught on _send_error_message : {exception}",
            file=sys.stderr,
        )
        traceback.print_exc()

async def _send_eoc_to_parent(self, turn_context: TurnContext, error: Exception):
    try:
        # Send an EndOfConversation activity to the skill caller with the error to end the conversation,
        # and let the caller decide what to do.
        end_of_conversation = Activity(type=ActivityTypes.end_of_conversation)
        end_of_conversation.code = "SkillError"
        end_of_conversation.text = str(error)

        await turn_context.send_activity(end_of_conversation)
    except Exception as exception:
        print(
            f"\n Exception caught on _send_eoc_to_parent : {exception}",
            file=sys.stderr,
        )
        traceback.print_exc()

Inscription du service

L’adaptateur Bot Framework utilise un objet de configuration d’authentification (défini quand l’adaptateur est créé) pour valider l’en-tête d’authentification sur les demandes entrantes.

Cet exemple ajoute la validation des revendications à la configuration de l’authentification et utilise l’adaptateur de compétences avec le gestionnaire d’erreurs décrit dans la section précédente.

C#

EchoSkillBot\Startup.cs

    options.SerializerSettings.MaxDepth = HttpHelper.BotMessageSerializerSettings.MaxDepth;
});

// Register AuthConfiguration to enable custom claim validation.
services.AddSingleton(sp =>
{
    var allowedCallers = new List<string>(sp.GetService<IConfiguration>().GetSection("AllowedCallers").Get<string[]>());

    var claimsValidator = new AllowedCallersClaimsValidator(allowedCallers);

    // If TenantId is specified in config, add the tenant as a valid JWT token issuer for Bot to Skill conversation.
    // The token issuer for MSI and single tenant scenarios will be the tenant where the bot is registered.
    var validTokenIssuers = new List<string>();
    var tenantId = sp.GetService<IConfiguration>().GetSection(MicrosoftAppCredentials.MicrosoftAppTenantIdKey)?.Value;

    if (!string.IsNullOrWhiteSpace(tenantId))
    {
        // For SingleTenant/MSI auth, the JWT tokens will be issued from the bot's home tenant.
        // Therefore, these issuers need to be added to the list of valid token issuers for authenticating activity requests.
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidTokenIssuerUrlTemplateV1, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidTokenIssuerUrlTemplateV2, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV1, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV2, tenantId));
    }

    return new AuthenticationConfiguration
    {
        ClaimsValidator = claimsValidator,
        ValidTokenIssuers = validTokenIssuers
    };
});

// Create the Bot Framework Authentication to be used with the Bot Adapter.
services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();

JavaScript

echo-skill-bot/index.js

const allowedCallers = (process.env.AllowedCallers || '').split(',').filter((val) => val) || [];

const claimsValidators = allowedCallersClaimsValidator(allowedCallers);

// If the MicrosoftAppTenantId is specified in the environment config, add the tenant as a valid JWT token issuer for Bot to Skill conversation.
// The token issuer for MSI and single tenant scenarios will be the tenant where the bot is registered.
let validTokenIssuers = [];
const { MicrosoftAppTenantId } = process.env;

if (MicrosoftAppTenantId) {
    // For SingleTenant/MSI auth, the JWT tokens will be issued from the bot's home tenant.
    // Therefore, these issuers need to be added to the list of valid token issuers for authenticating activity requests.
    validTokenIssuers = [
        `${ AuthenticationConstants.ValidTokenIssuerUrlTemplateV1 }${ MicrosoftAppTenantId }/`,
        `${ AuthenticationConstants.ValidTokenIssuerUrlTemplateV2 }${ MicrosoftAppTenantId }/v2.0/`,
        `${ AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV1 }${ MicrosoftAppTenantId }/`,
        `${ AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV2 }${ MicrosoftAppTenantId }/v2.0/`
    ];
}

// Define our authentication configuration.
const authConfig = new AuthenticationConfiguration([], claimsValidators, validTokenIssuers);

const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
    MicrosoftAppId: process.env.MicrosoftAppId,
    MicrosoftAppPassword: process.env.MicrosoftAppPassword,
    MicrosoftAppType: process.env.MicrosoftAppType,
    MicrosoftAppTenantId: process.env.MicrosoftAppTenantId
});

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env, credentialsFactory, authConfig);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

Java

echoSkillBot\Application.java

@Override
public AuthenticationConfiguration getAuthenticationConfiguration(Configuration configuration) {
    AuthenticationConfiguration authenticationConfiguration = new AuthenticationConfiguration();
    authenticationConfiguration.setClaimsValidator(
        new AllowedCallersClaimsValidator(Arrays.asList(configuration.getProperties(configKey)))
    );
    return authenticationConfiguration;
}

Python

echo-skill-bot/app.py

CLAIMS_VALIDATOR = AllowedCallersClaimsValidator(CONFIG)
AUTH_CONFIG = AuthenticationConfiguration(
    claims_validator=CLAIMS_VALIDATOR.claims_validator
)
# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
SETTINGS = ConfigurationBotFrameworkAuthentication(
    CONFIG,
    auth_configuration=AUTH_CONFIG,
)
ADAPTER = AdapterWithErrorHandler(SETTINGS)

Manifeste de compétence

Un manifeste de compétence est un fichier JSON qui décrit les activités que la compétence peut effectuer, ses paramètres d’entrée et de sortie, ainsi que ses points de terminaison. Le manifeste contient les informations dont vous avez besoin pour accéder à la compétence d’un autre bot. La version la plus récente du schéma est v2.1.

C#

EchoSkillBot\wwwroot\manifest\echoskillbot-manifest-1.0.json

{
  "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
  "$id": "EchoSkillBot",
  "name": "Echo Skill bot",
  "version": "1.0",
  "description": "This is a sample echo skill",
  "publisherName": "Microsoft",
  "privacyUrl": "https://echoskillbot.contoso.com/privacy.html",
  "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
  "license": "",
  "iconUrl": "https://echoskillbot.contoso.com/icon.png",
  "tags": [
    "sample",
    "echo"
  ],
  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV3",
      "description": "Default endpoint for the skill",
      "endpointUrl": "http://echoskillbot.contoso.com/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

JavaScript

echo-skill-bot/manifest/echoskillbot-manifest-1.0.json

{
  "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
  "$id": "EchoSkillBot",
  "name": "Echo Skill bot",
  "version": "1.0",
  "description": "This is a sample echo skill",
  "publisherName": "Microsoft",
  "privacyUrl": "https://echoskillbot.contoso.com/privacy.html",
  "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
  "license": "",
  "iconUrl": "https://echoskillbot.contoso.com/icon.png",
  "tags": [
    "sample",
    "echo"
  ],
  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV3",
      "description": "Default endpoint for the skill",
      "endpointUrl": "http://echoskillbot.contoso.com/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Java

DialogSkillBot\Webapp\manifest\echoskillbot-manifest-1.0.json

{
    "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
    "$id": "EchoSkillBot",
    "name": "Echo Skill bot",
    "version": "1.0",
    "description": "This is a sample echo skill",
    "publisherName": "Microsoft",
    "privacyUrl": "https://echoskillbot.contoso.com/privacy.html",
    "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
    "license": "",
    "iconUrl": "https://echoskillbot.contoso.com/icon.png",
    "tags": [
      "sample",
      "echo"
    ],
    "endpoints": [
      {
        "name": "default",
        "protocol": "BotFrameworkV3",
        "description": "Default endpoint for the skill",
        "endpointUrl": "http://echoskillbot.contoso.com/api/messages",
        "msAppId": "00000000-0000-0000-0000-000000000000"
      }
    ]
  }

Python

echo_skill_bot/wwwroot/manifest/echoskillbot-manifest-1.0.json

{
    "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
    "$id": "EchoSkillBot",
    "name": "Echo Skill bot",
    "version": "1.0",
    "description": "This is a sample echo skill",
    "publisherName": "Microsoft",
    "privacyUrl": "https://echoskillbot.contoso.com/privacy.html",
    "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
    "license": "",
    "iconUrl": "https://echoskillbot.contoso.com/icon.png",
    "tags": [
      "sample",
      "echo"
    ],
    "endpoints": [
      {
        "name": "default",
        "protocol": "BotFrameworkV3",
        "description": "Default endpoint for the skill",
        "endpointUrl": "http://echoskillbot.contoso.com/api/messages",
        "msAppId": "00000000-0000-0000-0000-000000000000"
      }
    ]
  }

Le schéma de manifeste de compétence est un fichier JSON qui décrit le schéma du manifeste de compétence. La version actuelle du schéma est 2.1.0.

Tester la compétence

À ce stade, vous pouvez tester la compétence dans l’émulateur comme s’il s’agissait d’un bot normal. Toutefois, pour la tester en tant que compétence, vous devez implémenter un consommateur de compétences.

Téléchargez et installez la dernière version de Bot Framework Emulator.

1. Exécutez le bot de compétences echo localement sur votre ordinateur. Si vous avez besoin d'instructions, reportez-vous au fichier README de l'échantillon C#, JavaScript, Java ou Python.
2. Utilisez l’émulateur pour tester le bot comme indiqué ci-dessous. Lorsque vous envoyez un message « fin » ou « arrêter » à la compétence, cela envoie une activité endOfConversation en plus du message de réponse. La compétence envoie l’activité endOfConversation pour indiquer qu’elle est terminée.

Plus d'informations sur le débogage

Étant donné que le trafic entre les compétences et les consommateurs de compétences est authentifié, des étapes supplémentaires sont nécessaires pour déboguer ces bots.

• Le consommateur de compétences et toutes les compétences qu'il consomme, directement ou indirectement, doivent être en cours d'exécution.
• Si les bots s'exécutent localement et si l'un des bots a un ID d'application et un mot de passe, tous les bots doivent avoir des identifiants et des mots de passe valides.
• Si les bots sont tous déployés, découvrez comment déboguer un bot à partir de n'importe quel chaîne à l'aide de ngrok.
• Si certains des bots s'exécutent localement et que d'autres sont déployés, découvrez comment déboguer une compétence ou un consommateur de compétences.

Dans le cas contraire, vous pouvez déboguer un consommateur de compétences ou une compétence comme vous déboguez d'autres bots. Pour plus d'informations, consultez Débogage d'un bot et Débogage avec Bot Framework Emulator.

Étapes suivantes

Implémenter une compétence pour Power Virtual Agents