Implementare un'abilità

EchoSkillBot\appsettings.json

Facoltativamente, aggiungere le informazioni sull'identità della competenza al file di appsettings.json.

{
  "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": [ "*" ]
}

echo-skill-bot/.env

Facoltativamente aggiungere le informazioni sull'identità dell'abilità nel file .env.

MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
AllowedCallers=*

DialogSkillBot\resources\application.properties

Opzionalmente, aggiungere l'ID e la password dell'app di abilità al file application.properties.

Facoltativamente, aggiungere l'ID e la password dell'app della competenza al file di config.py.

config.py

APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")

# Callers to only those specified, '*' allows any caller.

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

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

echoSkillBot\EchoBot.java

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.'
            )
        )

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

echo-skill-bot/bot.js

Usare il metodo onUnrecognizedActivityType per aggiungere una logica di fine conversazione. Nel gestore, controllare se l'type dell'attività non riconosciuta è uguale a 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();
});

echoSkillBot\EchoBot.java

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

L'SDK fornisce una classe che aggiunge l'autorizzazione AllowedCallersClaimsValidator a livello di applicazione in base a un semplice elenco di ID delle applicazioni autorizzate a chiamare la competenza. Se l'elenco contiene un asterisco (*), tutti i chiamanti sono consentiti. Il validator di attestazioni è configurato in Startup.cs.

L'SDK fornisce una classe che aggiunge l'autorizzazione allowedCallersClaimsValidator a livello di applicazione in base a un semplice elenco di ID delle applicazioni autorizzate a chiamare la competenza. Se l'elenco contiene un asterisco (*), tutti i chiamanti sono consentiti. Il validator delle attestazioni è configurato in index.js.

L'SDK fornisce una classe che aggiunge l'autorizzazione AllowedCallersClaimsValidator a livello di applicazione in base a un semplice elenco di ID delle applicazioni autorizzate a chiamare la competenza. Se l'elenco contiene un asterisco (*), tutti i chiamanti sono consentiti. Il validator delle attestazioni è configurato in Application.java.

Definire un metodo di convalida delle attestazioni che genera un errore per rifiutare una richiesta in arrivo.

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

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

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

echoSkillBot\SkillAdapterWithErrorHandler.java

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

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

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

echoSkillBot\Application.java

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)

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

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

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

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