Implementieren einer Qualifikation

GILT FÜR: SDK v4

Sie können Qualifikationen verwenden, um einen anderen Bot zu erweitern. Eine Qualifikation (Englisch: Skill) ist ein Bot, der eine Reihe von Aufgaben für einen anderen Bot durchführen kann.

• Ein Manifest beschreibt die Schnittstelle einer Fähigkeit. Entwickler, die keinen Zugriff auf den Quellcode der Qualifikation haben, können die Informationen im Manifest nutzen, um ihren „Skill-Consumer“ (also den „Verbraucher der Qualifikation“) zu entwerfen.
• Für eine Qualifikation kann die Anspruchsüberprüfung verwendet werden, um zu verwalten, welche Bots oder Benutzer darauf zugreifen können.

In diesem Artikel wird veranschaulicht, wie Sie eine Qualifikation implementieren, die die Eingabe des Benutzers wiederholt.

Einige Typen von Skillconsumern sind nicht in der Lage, einige Typen von Skill-Bots zu verwenden. In der folgenden Tabelle wird beschrieben, welche Kombinationen unterstützt werden.

	Mehrinstanzenfähiger Skill	Single-Tenant-Skill	Skill der benutzerseitig zugewiesenen verwalteten Identität
Mehrinstanzenfähige Verbraucher	Unterstützt	Nicht unterstützt	Nicht unterstützt
Einzelinstanzenfähige Verbraucher	Nicht unterstützt	Unterstützt, wenn beide Apps zu demselben Mandanten gehören	Unterstützt, wenn beide Apps zu demselben Mandanten gehören
Consumer einer benutzerseitig zugewiesenen verwalteten Identität	Nicht unterstützt	Unterstützt, wenn beide Apps zu demselben Mandanten gehören	Unterstützt, wenn beide Apps zu demselben Mandanten gehören

Hinweis

Die JavaScript-, C#- und Python-SDKs für Bot Framework werden weiterhin unterstützt, das Java-SDK wird jedoch eingestellt und der langfristige Support endet im November 2023.

Bestehende Bots, die mit dem Java SDK erstellt wurden, werden weiterhin funktionieren.

Für das erstellen eines neuen Bots sollten Sie Microsoft Copilot Studio verwenden und lesen, wie Sie die richtige Copilot-Lösung auswählen.

Weitere Informationen finden Sie unter Die Zukunft des Bot-Design.

Voraussetzungen

• Kenntnisse: Funktionsweise von Bots und Qualifikationen.
• Ein Azure-Abonnement (für die Bereitstellung Ihres Skills). Falls Sie kein Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
• Eine Kopie des Beispiels skills simple bot-to-bot in C#, JavaScript, Java oder Python.

Hinweis

Ab Version 4.11 benötigen Sie keine App-ID und kein Passwort, um einen Skill lokal im Bot Framework Emulator zu testen. Ein Azure-Abonnement ist weiterhin erforderlich, um Ihre Skills in Azure bereitzustellen.

Informationen zu diesem Beispiel

Das Beispiel skills simple bot-to-bot enthält Projekte für zwei Bots:

• Echo Skill Bot (Echo-Bot für Qualifikation) zum Implementieren der Qualifikation.
• Simple Root Bot (einfacher Stamm-Bot) zum Implementieren eines Stamm-Bots, der die Qualifikation nutzt.

Der Schwerpunkt dieses Artikels liegt auf der Qualifikation, und auch die Unterstützungslogik im Bot und Adapter wird beschrieben.

C#

JavaScript

Java

Python

Weitere Informationen zum einfachen Stamm-Bot finden Sie unter Implementieren eines Skill-Consumers.

Ressourcen

Bei eingesetzten Bots erfordert die Bot-zu-Bot-Authentifizierung, dass jeder teilnehmende Bot über gültige Identitätsinformationen verfügt. Sie können jedoch multiinstanzenfähige Fähigkeiten und Qualifikationskunden lokal mit dem Emulator ohne App-ID und Kennwort testen.

Um den Skill für benutzerseitige Bots verfügbar zu machen, registrieren Sie den Skill bei Azure. Weitere Informationen finden Sie unter Registrieren eines Bots bei Azure KI Bot Service.

Anwendungskonfiguration

Fügen Sie optional die Identitätsinformationen der Skills zur Konfigurationsdatei der Skills hinzu. Wenn entweder der Skill oder der Skillconsumer Identitätsinformationen liefert, müssen beide dies tun.

Über das Array allowed callers (Zulässige Aufrufer) kann festgelegt werden, welche Skill-Consumer auf die Qualifikation zugreifen können. Fügen Sie ein "*"-Element hinzu, um Anrufe von jedem Qualifikationsanwender anzunehmen.

Hinweis

Wenn Sie Ihre Skills lokal ohne Bot-Identitätsinformationen testen, führen weder der Skill noch der Skillconsumer den Code aus, um die Anspruchsüberprüfung durchzuführen.

C#

EchoSkillBot\appsettings.json

Fügen Sie optional die Identitätsinformationen des Skills zur Datei „appsettings.json“ hinzu.

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

Fügen Sie optional die Identitätsinformationen des Skills zur Datei „.env“ hinzu.

MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
AllowedCallers=*

Java

DialogSkillBot\resources\application.properties

Fügen Sie optional die App-ID und das Kennwort der Qualifikation der Datei „application.properties“ hinzu.

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

Fügen Sie optional die App-ID und das Kennwort der Qualifikation der Datei „config.py“ hinzu.

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.

Aktivitätshandlerlogik

So akzeptieren Sie Eingabeparameter

Der Skill-Consumer kann Informationen an die Qualifikation senden. Eine Möglichkeit, Informationen dieser Art zu akzeptieren, ist die value-Eigenschaft in eingehenden Nachrichten. Eine andere Möglichkeit ist das Verarbeiten des Ereignisses und das Aufrufen von Aktivitäten.

Für die Qualifikation in diesem Beispiel werden keine Eingabeparameter akzeptiert.

So setzen Sie eine Bot-Konversation fort oder schließen sie ab

Wenn die Qualifikation eine Aktivität sendet, sollte diese vom Skill-Consumer an den Benutzer weitergeleitet werden.

Sie müssen jedoch eine endOfConversation Aktivität senden, wenn die Fähigkeiten abgeschlossen sind. Andernfalls leitet der Qualifikationsverbraucher die Benutzeraktivitäten weiter an die Qualifikation weiter. Optional können Sie die value-Eigenschaft der Aktivität verwenden, um einen Rückgabewert einzubinden, und mit der code-Eigenschaft der Aktivität angeben, warum die Qualifikation beendet wird.

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

So brechen Sie die Qualifikation ab

Für Qualifikationen mit mehreren Durchläufen können Sie auch endOfConversation-Aktivitäten von einem Skill-Consumer akzeptieren, damit der Consumer die aktuelle Konversation abbrechen kann.

Die Logik für diese Qualifikation ändert sich von Durchlauf zu Durchlauf nicht. Wenn Sie eine Qualifikation implementieren, von der Konversationsressourcen zugeordnet werden, sollten Sie dem Handler für das Ende der Konversation (endOfConversation) Code für die Ressourcenbereinigung hinzufügen.

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

Verwenden Sie die onUnrecognizedActivityType-Methode, um Logik für das Ende der Konversation hinzuzufügen. Überprüfen Sie im Handler, ob der type der nicht erkannten Aktivität endOfConversation lautet.

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

Validierungssteuerelement für Ansprüche

In diesem Beispiel wird eine Liste mit zulässigen Aufrufern für die Anspruchsüberprüfung verwendet. Die Konfigurationsdatei der Qualifikation definiert die Liste. Das Validator-Objekt liest dann die Liste vor.

Sie müssen der Authentifizierungskonfiguration ein Validierungssteuerelement für Ansprüche hinzufügen. Die Ansprüche werden nach dem Authentifizierungsheader ausgewertet. Ihr Überprüfungscode sollte einen Fehler oder eine Ausnahme auslösen, um die Anforderung abzulehnen. Es gibt viele Gründe, aus denen Sie eine andernfalls authentifizierte Anforderung ablehnen möchten. Zum Beispiel:

• Die Qualifikation ist Teil eines kostenpflichtigen Diensts. Benutzer, die nicht in der Datenbank sind, sollten keinen Zugriff haben.
• Es handelt sich um eine proprietäre Qualifikation. Nur bestimmte Skill-Consumer können die Qualifikation aufrufen.

Wichtig

Wenn Sie keinen Anspruchsprüfer bereitstellen, wird Ihr Bot einen Fehler oder eine Ausnahme erzeugen, wenn er eine Aktivität vom Skillconsumer erhält.

C#

Das SDK stellt eine AllowedCallersClaimsValidator-Klasse bereit, die die Autorisierung auf Anwendungsebene basierend auf einer einfachen Liste der IDs der Anwendungen hinzufügt, die den Skill aufrufen dürfen. Wenn die Liste ein Sternchen (*) enthält, sind alle Anrufer zulässig. Der Anspruchsprüfer wird in Startup.cs konfiguriert.

JavaScript

Das SDK stellt eine allowedCallersClaimsValidator-Klasse bereit, die die Autorisierung auf Anwendungsebene basierend auf einer einfachen Liste der IDs der Anwendungen hinzufügt, die den Skill aufrufen dürfen. Wenn die Liste ein Sternchen (*) enthält, sind alle Anrufer zulässig. Der Anspruchsprüfer wird in index.js konfiguriert.

Java

Das SDK stellt eine AllowedCallersClaimsValidator-Klasse bereit, die die Autorisierung auf Anwendungsebene basierend auf einer einfachen Liste der IDs der Anwendungen hinzufügt, die den Skill aufrufen dürfen. Wenn die Liste ein Sternchen (*) enthält, sind alle Anrufer zulässig. Der Anspruchsprüfer wird in Application.java konfiguriert.

Python

Definieren Sie eine Methode für die Überprüfung von Ansprüchen, die einen Fehler auslöst, um eine eingehende Anforderung abzulehnen.

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

Adapter für Qualifikation

Wenn ein Fehler auftritt, sollte der Adapter der Qualifikation den Konversationszustand für die Qualifikation löschen und eine endOfConversation-Aktivität an den Skill-Consumer senden. Um zu signalisieren, dass die Fähigkeit aufgrund eines Fehlers beendet wurde, verwenden Sie die Codeeigenschaft der Aktivität.

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

Dienstregistrierung

Der Bot Framework-Adapter nutzt ein Objekt für die Authentifizierungskonfiguration (wird bei der Erstellung des Adapters festgelegt), um den Authentifizierungsheader für eingehende Anforderungen zu überprüfen.

In diesem Beispiel wird der Authentifizierungskonfiguration eine Überprüfung für Ansprüche hinzugefügt und der Adapter für Qualifikationen mit Fehlerhandler verwendet, der im vorherigen Abschnitt beschrieben wurde.

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)

Qualifikationsmanifest

Ein Qualifikationsmanifest ist eine JSON-Datei, in der die von der Qualifikation durchführbaren Aktivitäten, die Eingabe- und Ausgabeparameter und die Endpunkte der Qualifikation beschrieben sind. Das Manifest enthält die Informationen, die Sie für den Zugriff auf die Qualifikation mit einem anderen Bot benötigen. Die neueste Schema-Version ist 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"
      }
    ]
  }

Das Schema des Qualifikationsmanifests ist eine JSON-Datei, in der das Schema des Qualifikationsmanifests beschrieben ist. Die aktuelle Schemaversion ist 2.1.0.

Testen der Qualifikation

An diesem Punkt können Sie die Qualifikation im Emulator testen, als ob es sich um einen regulären Bot handeln würde. Zum Testen als Qualifikation müssen Sie aber einen Skill-Consumer implementieren.

Laden Sie die aktuelle Version von Bot Framework Emulator herunter, und installieren Sie sie.

1. Führen Sie den „Echo Skill Bot“ lokal auf Ihrem Computer aus. Wenn Sie eine Anleitung benötigen, helfen Ihnen die README-Datei des Beispiels für C#, JavaScript, Java oder Python weiter.
2. Testen Sie den Bot im Emulator. Wenn Sie eine „end“- oder „stop“-Nachricht an die Qualifikation senden, wird zusätzlich zur Antwortnachricht eine endOfConversation-Aktivität gesendet. Die Fähigkeit sendet die endOfConversation Aktivität, um anzugeben, dass die Fähigkeit abgeschlossen ist.

Mehr über Debuggen

Da der Datenverkehr zwischen Skills und Skill-Verbraucher authentifiziert wird, gibt es zusätzliche Schritte beim Debuggen solcher Bots.

• Der Skill-Verbraucher und alle Skills, die er direkt oder indirekt verbraucht, müssen ausgeführt werden.
• Wenn die Bots lokal ausgeführt werden und einer der Bots über eine App-ID und ein Passwort verfügt, müssen alle Bots gültige IDs und Passwörter besitzen.
• Wenn alle Bots bereitgestellt werden, erfahren Sie, wie Sie einen Bot über einen beliebigen Kanal mithilfe von Devtunnel debuggen.
• Wenn einige der Bots lokal ausgeführt werden und einige bereitgestellt werden, erfahren Sie, wie Sie einen Skill oder einen Skill-Verbraucher debuggen.

Andernfalls können Sie einen Skill-Verbraucher oder einen Skill ähnlich debuggen, wie Sie andere Bots debuggen. Weitere Informationen finden Sie unter Debuggen eines Bots und Debuggen mit dem Bot Framework Emulator.

Nächste Schritte

Implementieren einer Fähigkeit für Copilot Studio