Enviar anexos de mídia com o Bot Framework SDK

APLICA-SE A: SDK v4

As mensagens trocadas entre o usuário e o bot podem conter anexos de mídia, como imagens, vídeo, áudio e arquivos. O SDK do Bot Framework suporta a tarefa de enviar mensagens avançadas para o usuário. Para determinar o tipo de mensagens avançadas que um canal (Facebook, Slack e assim por diante) suporta, consulte a documentação do canal para obter informações sobre limitações.

Nota

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser suportados, no entanto, o Java SDK está sendo desativado com suporte final de longo prazo terminando em novembro de 2023. Apenas segurança crítica e correções de bugs dentro deste repositório serão realizadas.

Os bots existentes construídos com o Java SDK continuarão a funcionar.

Para a criação de novos bots, considere usar o Power Virtual Agents e leia sobre como escolher a solução de chatbot certa.

Para obter mais informações, consulte O futuro da criação de bots.

Pré-requisitos

• Conhecimento básico de bots.
• O código neste artigo é baseado nos seguintes exemplos:
  • Usando cartões: C#, JavaScript, Java, Python
  • Tratamento de anexos: C#, JavaScript, Java, Python
  • Ações sugeridas: C#, JavaScript, Java, Python

Enviar anexos

Para enviar o conteúdo do usuário, como uma imagem ou um vídeo, você pode adicionar um anexo ou uma lista de anexos a uma mensagem.

Consulte Projetar a experiência do usuário para obter exemplos de cartões disponíveis.

Consulte também Qual é o limite de tamanho de um arquivo transferido usando canais? nas Perguntas frequentes.

C#

Todo o código-fonte mostrado nesta seção é baseado no exemplo Manipulando anexos .

A Attachments propriedade do Activity objeto contém uma matriz de objetos que representam os anexos de Attachment mídia e cartões avançados anexados à mensagem. Para adicionar um anexo de mídia a uma mensagem, crie um Attachment objeto para a reply atividade e defina as ContentTypepropriedades , ContentUrle Name .

Para criar a mensagem de resposta, defina o texto e, em seguida, configure os anexos. A atribuição dos anexos à resposta é a mesma para cada tipo de anexo, no entanto, os vários anexos são configurados e definidos de forma diferente, como visto nos trechos a seguir. O código abaixo está configurando a resposta para um anexo embutido:

Bots/AnexosBot.cs

{
    reply = MessageFactory.Text("This is an inline attachment.");

Em seguida, examinamos os tipos de anexos. O primeiro é um anexo embutido:

Bots/AnexosBot.cs

{
    var imagePath = Path.Combine(Environment.CurrentDirectory, @"Resources", "architecture-resize.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));

    return new Attachment
    {
        Name = @"Resources\architecture-resize.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}

Em seguida, um anexo carregado:

Bots/AnexosBot.cs

{
    if (string.IsNullOrWhiteSpace(serviceUrl))
    {
        throw new ArgumentNullException(nameof(serviceUrl));
    }

    if (string.IsNullOrWhiteSpace(conversationId))
    {
        throw new ArgumentNullException(nameof(conversationId));
    }

    var imagePath = Path.Combine(Environment.CurrentDirectory, @"Resources", "architecture-resize.png");

    var connector = turnContext.TurnState.Get<IConnectorClient>() as ConnectorClient;
    var attachments = new Attachments(connector);
    var response = await attachments.Client.Conversations.UploadAttachmentAsync(
        conversationId,
        new AttachmentData
        {
            Name = @"Resources\architecture-resize.png",
            OriginalBase64 = File.ReadAllBytes(imagePath),
            Type = "image/png",
        },
        cancellationToken);

    var attachmentUri = attachments.GetAttachmentUri(response.Id);

    return new Attachment
    {
        Name = @"Resources\architecture-resize.png",
        ContentType = "image/png",
        ContentUrl = attachmentUri,
    };
}

Por último, um anexo Internet:

Bots/AnexosBot.cs

    {
        // ContentUrl must be HTTPS.
        return new Attachment
        {
            Name = @"Resources\architecture-resize.png",
            ContentType = "image/png",
            ContentUrl = "https://docs.microsoft.com/en-us/bot-framework/media/how-it-works/architecture-resize.png",
        };
    }
}

JavaScript

O código-fonte a seguir é do exemplo Manipulando anexos .

Para usar anexos, inclua as seguintes bibliotecas no bot:

bots/anexosBot.js

const { ActivityHandler, ActionTypes, ActivityTypes, CardFactory } = require('botbuilder');

Para criar a mensagem de resposta, defina o texto e, em seguida, configure os anexos. A atribuição dos anexos à resposta é a mesma para cada tipo de anexo, no entanto, os vários anexos são configurados e definidos de forma diferente, como visto nos trechos a seguir. O código abaixo está configurando a resposta para um anexo embutido:

bots/anexosBot.js

const reply = { type: ActivityTypes.Message };
    reply.text = 'This is an inline attachment.';
    reply.attachments = [this.getInlineAttachment()];

Para enviar ao usuário um único conteúdo, como uma imagem ou um vídeo, você pode enviar mídia de algumas maneiras diferentes. Primeiro, como um anexo embutido:

bots/anexosBot.js

getInlineAttachment() {
    const imageData = fs.readFileSync(path.join(__dirname, '../resources/architecture-resize.png'));
    const base64Image = Buffer.from(imageData).toString('base64');

    return {
        name: 'architecture-resize.png',
        contentType: 'image/png',
        contentUrl: `data:image/png;base64,${ base64Image }`
    };
}

Em seguida, um anexo carregado:

bots/anexosBot.js

async getUploadedAttachment(turnContext) {
    const imageData = fs.readFileSync(path.join(__dirname, '../resources/architecture-resize.png'));
    const connectorFactory = turnContext.turnState.get(turnContext.adapter.ConnectorFactoryKey);
    const connector = await connectorFactory.create(turnContext.activity.serviceUrl);
    const conversationId = turnContext.activity.conversation.id;
    const response = await connector.conversations.uploadAttachment(conversationId, {
        name: 'architecture-resize.png',
        originalBase64: imageData,
        type: 'image/png'
    });

    // Retrieve baseUri from ConnectorClient for... something.
    const baseUri = connector.baseUri;
    const attachmentUri = baseUri + (baseUri.endsWith('/') ? '' : '/') + `v3/attachments/${ encodeURI(response.id) }/views/original`;
    return {
        name: 'architecture-resize.png',
        contentType: 'image/png',
        contentUrl: attachmentUri
    };

Por último, um anexo da Internet contido num URL:

bots/anexosBot.js

getInternetAttachment() {
    // NOTE: The contentUrl must be HTTPS.
    return {
        name: 'architecture-resize.png',
        contentType: 'image/png',
        contentUrl: 'https://docs.microsoft.com/en-us/bot-framework/media/how-it-works/architecture-resize.png'
    };
}

Java

O código-fonte mostrado nesta seção é baseado no exemplo Manipulando anexos .

O getAttachments() método do Activity objeto contém uma matriz de objetos que representam os anexos de Attachment mídia e cartões avançados anexados à mensagem. Para adicionar um anexo de mídia a uma mensagem, crie um Attachment objeto para a reply atividade e defina as ContentTypepropriedades , ContentUrle Name .

Para criar a mensagem de resposta, defina o texto e, em seguida, configure os anexos. A atribuição dos anexos à resposta é a mesma para cada tipo de anexo, no entanto, os vários anexos são configurados e definidos de forma diferente, como visto nos trechos a seguir. O código abaixo está configurando a resposta para um anexo embutido:

AttachmentsBot.java

result = getInlineAttachment()
    .thenApply(attachment -> {
        Activity reply = MessageFactory.text("This is an inline attachment.");
        reply.setAttachment(attachment);
        return reply;
    });

Em seguida, examinamos os tipos de anexos. O primeiro é um anexo embutido:

AttachmentsBot.java

// Creates an inline attachment sent from the bot to the user using a base64 string.
// Using a base64 string to send an attachment will not work on all channels.
// Additionally, some channels will only allow certain file types to be sent this way.
// For example a .png file may work but a .pdf file may not on some channels.
// Please consult the channel documentation for specifics.
private CompletableFuture<Attachment> getInlineAttachment() {
    return getEncodedFileData("architecture-resize.png")
        .thenApply(encodedFileData -> {
            Attachment attachment = new Attachment();
            attachment.setName("architecture-resize.png");
            attachment.setContentType("image/png");
            attachment.setContentUrl("data:image/png;base64," + encodedFileData);
            return attachment;
        });
}

Em seguida, um anexo carregado:

AttachmentsBot.java

private CompletableFuture<Attachment> getUploadedAttachment(TurnContext turnContext, String serviceUrl, String conversationId) {
    if (StringUtils.isEmpty(serviceUrl)) {
        return Async.completeExceptionally(new IllegalArgumentException("serviceUrl"));
    }
    if (StringUtils.isEmpty(conversationId)) {
        return Async.completeExceptionally(new IllegalArgumentException("conversationId"));
    }

    ConnectorClient connector = turnContext.getTurnState()
        .get(BotFrameworkAdapter.CONNECTOR_CLIENT_KEY);
    Attachments attachments = connector.getAttachments();

    return getFileData("architecture-resize.png")
        .thenCompose(fileData -> {
            AttachmentData attachmentData = new AttachmentData();
            attachmentData.setName("architecture-resize.png");
            attachmentData.setType("image/png");
            attachmentData.setOriginalBase64(fileData);

            return connector.getConversations().uploadAttachment(conversationId, attachmentData)
                .thenApply(response -> {
                    String attachmentUri = attachments.getAttachmentUri(response.getId());

                    Attachment attachment = new Attachment();
                    attachment.setName("architecture-resize.png");
                    attachment.setContentType("image/png");
                    attachment.setContentUrl(attachmentUri);

                    return attachment;
                });
        });
}

Por último, um anexo Internet:

AttachmentsBot.java

// Creates an Attachment to be sent from the bot to the user from a HTTP URL.
private static Attachment getInternetAttachment() {
    // ContentUrl must be HTTPS.
    Attachment attachment = new Attachment();
    attachment.setName("architecture-resize.png");
    attachment.setContentType("image/png");
    attachment.setContentUrl("https://docs.microsoft.com/en-us/bot-framework/media/how-it-works/architecture-resize.png");
    return attachment;
}

Python

O código-fonte a seguir é do exemplo Manipulando anexos .

Para criar a mensagem de resposta, defina o texto e, em seguida, configure os anexos. A atribuição dos anexos à resposta é a mesma para cada tipo de anexo, no entanto, os vários anexos são configurados e definidos de forma diferente, como visto nos trechos a seguir.

O código abaixo está configurando a resposta para um anexo embutido:

bots/attachments_bot.py

reply.text = "This is an inline attachment."
reply.attachments = [self._get_inline_attachment()]

Para enviar ao usuário um único conteúdo, como uma imagem ou um vídeo, você pode enviar mídia de algumas maneiras diferentes. Primeiro, como um anexo embutido:

bots/attachments_bot.py

def _get_inline_attachment(self) -> Attachment:
    """
    Creates an inline attachment sent from the bot to the user using a base64 string.
    Using a base64 string to send an attachment will not work on all channels.
    Additionally, some channels will only allow certain file types to be sent this way.
    For example a .png file may work but a .pdf file may not on some channels.
    Please consult the channel documentation for specifics.
    :return: Attachment
    """
    file_path = os.path.join(os.getcwd(), "resources/architecture-resize.png")
    with open(file_path, "rb") as in_file:
        base64_image = base64.b64encode(in_file.read()).decode()

    return Attachment(
        name="architecture-resize.png",
        content_type="image/png",
        content_url=f"data:image/png;base64,{base64_image}",
    )

Em seguida, um anexo carregado:

bots/attachments_bot.py

async def _get_upload_attachment(self, turn_context: TurnContext) -> Attachment:
    """
    Creates an "Attachment" to be sent from the bot to the user from an uploaded file.
    :param turn_context:
    :return: Attachment
    """
    with open(
        os.path.join(os.getcwd(), "resources/architecture-resize.png"), "rb"
    ) as in_file:
        image_data = in_file.read()

    connector = await turn_context.adapter.create_connector_client(
        turn_context.activity.service_url
    )
    conversation_id = turn_context.activity.conversation.id
    response = await connector.conversations.upload_attachment(
        conversation_id,
        AttachmentData(
            name="architecture-resize.png",
            original_base64=image_data,
            type="image/png",
        ),
    )

    base_uri: str = connector.config.base_url
    attachment_uri = (
        base_uri
        + ("" if base_uri.endswith("/") else "/")
        + f"v3/attachments/{response.id}/views/original"
    )

    return Attachment(
        name="architecture-resize.png",
        content_type="image/png",
        content_url=attachment_uri,
    )

Por último, um anexo da Internet contido num URL:

bots/attachments_bot.py

def _get_internet_attachment(self) -> Attachment:
    """
    Creates an Attachment to be sent from the bot to the user from a HTTP URL.
    :return: Attachment
    """
    return Attachment(
        name="architecture-resize.png",
        content_type="image/png",
        content_url="https://docs.microsoft.com/en-us/bot-framework/media/how-it-works/architecture-resize.png",
    )

Se um anexo for uma imagem, áudio ou vídeo, o serviço Connector comunicará os dados do anexo ao canal de uma forma que permita que o canal processe esse anexo dentro da conversa. Se o anexo for um arquivo, a URL do arquivo será processada como um hiperlink dentro da conversa.

Enviar um cartão de herói

Além de simples anexos de imagem ou vídeo, você pode anexar um cartão herói, que permite combinar imagens e botões em um objeto, e enviá-los para o usuário. Markdown é suportado para a maioria dos campos de texto, mas o suporte pode variar de acordo com o canal.

C#

Para compor uma mensagem com um cartão herói e um botão, você pode anexar um HeroCard objeto a uma mensagem.

O código-fonte a seguir é do exemplo Manipulando anexos .

Bots/AnexosBot.cs

      private static async Task DisplayOptionsAsync(ITurnContext turnContext, CancellationToken cancellationToken)
      {
          // Create a HeroCard with options for the user to interact with the bot.
          var card = new HeroCard
          {
              Text = "You can upload an image or select one of the following choices",
              Buttons = new List<CardAction>
              {
                  // Note that some channels require different values to be used in order to get buttons to display text.
                  // In this code the emulator is accounted for with the 'title' parameter, but in other channels you may
                  // need to provide a value for other parameters like 'text' or 'displayText'.
                  new CardAction(ActionTypes.ImBack, title: "1. Inline Attachment", value: "1"),
                  new CardAction(ActionTypes.ImBack, title: "2. Internet Attachment", value: "2"),
                  new CardAction(ActionTypes.ImBack, title: "3. Uploaded Attachment", value: "3"),
              },
          };

          var reply = MessageFactory.Attachment(card.ToAttachment());
          await turnContext.SendActivityAsync(reply, cancellationToken);

JavaScript

Para compor uma mensagem com um cartão herói e um botão, você pode anexar um HeroCard objeto a uma mensagem.

O código-fonte a seguir é do exemplo Manipulando anexos .

bots/anexosBot.js

async displayOptions(turnContext) {
    const reply = { type: ActivityTypes.Message };

    // Note that some channels require different values to be used in order to get buttons to display text.
    // In this code the emulator is accounted for with the 'title' parameter, but in other channels you may
    // need to provide a value for other parameters like 'text' or 'displayText'.
    const buttons = [
        { type: ActionTypes.ImBack, title: '1. Inline Attachment', value: '1' },
        { type: ActionTypes.ImBack, title: '2. Internet Attachment', value: '2' },
        { type: ActionTypes.ImBack, title: '3. Uploaded Attachment', value: '3' }
    ];

    const card = CardFactory.heroCard('', undefined,
        buttons, { text: 'You can upload an image or select one of the following choices.' });

    reply.attachments = [card];

    await turnContext.sendActivity(reply);
}

Java

Para compor uma mensagem com um cartão herói e um botão, você pode anexar um HeroCard objeto a uma mensagem.

O código-fonte a seguir é do exemplo Manipulando anexos .

AttachmentsBot.java

private static CompletableFuture<Void> displayOptions(TurnContext turnContext) {
    // Create a HeroCard with options for the user to interact with the bot.
    HeroCard card = new HeroCard();
    card.setText("You can upload an image or select one of the following choices");

    // Note that some channels require different values to be used in order to get buttons to display text.
    // In this code the emulator is accounted for with the 'title' parameter, but in other channels you may
    // need to provide a value for other parameters like 'text' or 'displayText'.
    card.setButtons(
        new CardAction(ActionTypes.IM_BACK, "1. Inline Attachment", "1"),
        new CardAction(ActionTypes.IM_BACK, "2. Internet Attachment", "2"),
        new CardAction(ActionTypes.IM_BACK, "3. Uploaded Attachment", "3")
    );

    Activity reply = MessageFactory.attachment(card.toAttachment());
    return turnContext.sendActivity(reply).thenApply(resourceResponse -> null);
}    

Python

Para compor uma mensagem com um cartão herói e um botão, você pode anexar um HeroCard objeto a uma mensagem.

O código-fonte a seguir é do exemplo Manipulando anexos .

bots/attachments_bot.py

async def _display_options(self, turn_context: TurnContext):
    """
    Create a HeroCard with options for the user to interact with the bot.
    :param turn_context:
    :return:
    """

    # Note that some channels require different values to be used in order to get buttons to display text.
    # In this code the emulator is accounted for with the 'title' parameter, but in other channels you may
    # need to provide a value for other parameters like 'text' or 'displayText'.
    card = HeroCard(
        text="You can upload an image or select one of the following choices",
        buttons=[
            CardAction(
                type=ActionTypes.im_back, title="1. Inline Attachment", value="1"
            ),
            CardAction(
                type=ActionTypes.im_back, title="2. Internet Attachment", value="2"
            ),
            CardAction(
                type=ActionTypes.im_back, title="3. Uploaded Attachment", value="3"
            ),
        ],
    )

Processar eventos em cartões avançados

Para processar eventos em cartões avançados, use objetos de ação do cartão para especificar o que deve acontecer quando o usuário seleciona um botão ou toca em uma seção do cartão. Cada ação de cartão tem uma propriedade type e value .

Para funcionar corretamente, atribua um tipo de ação a cada item clicável em um cartão de herói. Esta tabela lista e descreve os tipos de ação disponíveis e o que deve estar na propriedade value associada. A messageBack ação do cartão tem um significado mais generalizado do que as outras ações do cartão. Consulte a seção Ação do cartão do esquema de atividade para obter mais informações sobre o messageBack e outros tipos de ação do cartão.

Tipo	Descrição	Valor
call	Inicia uma chamada telefónica.	Destino da chamada telefónica neste formato: tel:123123123123.
baixarArquivo	Transfere um ficheiro.	O URL do ficheiro a transferir.
imVoltar	Envia uma mensagem para o bot e publica uma resposta visível no chat.	Texto da mensagem a enviar.
messageVoltar	Representa uma resposta de texto a ser enviada através do sistema de chat.	Um valor programático opcional para incluir nas mensagens geradas.
openUrl	Abre um URL no navegador integrado.	O URL a abrir.
reproduzirÁudio	Reproduz áudio.	O URL do áudio a ser reproduzido.
reproduzirVídeo	Reproduz um vídeo.	O URL do vídeo a ser reproduzido.
postVoltar	Envia uma mensagem para o bot e pode não publicar uma resposta visível no chat.	Texto da mensagem a enviar.
showImage	Exibe uma imagem.	O URL da imagem a ser exibida.
iniciar sessão	Inicia um processo de entrada OAuth.	A URL do fluxo OAuth para iniciar.

Cartão de herói usando vários tipos de evento

O código a seguir mostra exemplos usando vários eventos de cartão avançado.

C#

Para obter exemplos de todos os cartões disponíveis, consulte o Exemplo de uso de cartões .

Cartões.cs

public static HeroCard GetHeroCard()
{
    var heroCard = new HeroCard
    {
        Title = "BotFramework Hero Card",
        Subtitle = "Microsoft Bot Framework",
        Text = "Build and connect intelligent bots to interact with your users naturally wherever they are," +
               " from text/sms to Skype, Slack, Office 365 mail and other popular services.",
        Images = new List<CardImage> { new CardImage("https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg") },
        Buttons = new List<CardAction> { new CardAction(ActionTypes.OpenUrl, "Get Started", value: "https://docs.microsoft.com/bot-framework") },
    };

    return heroCard;
}

Cartões.cs

public static SigninCard GetSigninCard()
{
    var signinCard = new SigninCard
    {
        Text = "BotFramework Sign-in Card",
        Buttons = new List<CardAction> { new CardAction(ActionTypes.Signin, "Sign-in", value: "https://login.microsoftonline.com/") },
    };

    return signinCard;
}

JavaScript

Para obter exemplos de todos os cartões disponíveis, consulte o Exemplo de uso de cartões .

diálogos/mainDialog.js

createHeroCard() {
    return CardFactory.heroCard(
        'BotFramework Hero Card',
        CardFactory.images(['https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg']),
        CardFactory.actions([
            {
                type: 'openUrl',
                title: 'Get started',
                value: 'https://docs.microsoft.com/en-us/azure/bot-service/'
            }
        ])
    );
}

diálogos/mainDialog.js

createOAuthCard() {
    return CardFactory.oauthCard(
        'OAuth connection', // Replace with the name of your Azure AD connection
        'Sign In',
        'BotFramework OAuth Card'
    );
}

Java

Para obter exemplos de todos os cartões disponíveis, consulte o Exemplo de uso de cartões .

Cartões.java

public static HeroCard getHeroCard() {
    HeroCard heroCard = new HeroCard();
    heroCard.setTitle("BotFramework Hero Card");
    heroCard.setSubtitle("Microsoft Bot Framework");
    heroCard.setText("Build and connect intelligent bots to interact with your users naturally wherever they are," +
                " from text/sms to Skype, Slack, Office 365 mail and other popular services.");
    heroCard.setImages(new CardImage("https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg"));
    heroCard.setButtons(new CardAction(ActionTypes.OPEN_URL, "Get Started", "https://docs.microsoft.com/bot-framework"));

    return heroCard;
}

Cartões.java

public static SigninCard getSigninCard() {
    SigninCard signinCard = new SigninCard();
    signinCard.setText("BotFramework Sign-in Card");
    signinCard.setButtons(new CardAction(ActionTypes.SIGNIN, "Sign-in", "https://login.microsoftonline.com/"));
    return signinCard;
}

Python

Para obter exemplos de todos os cartões disponíveis, consulte o Exemplo de uso de cartões .

diálogos/main_dialog.py

def create_hero_card(self) -> Attachment:
    card = HeroCard(
        title="",
        images=[
            CardImage(
                url="https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg"
            )
        ],
        buttons=[
            CardAction(
                type=ActionTypes.open_url,
                title="Get Started",
                value="https://docs.microsoft.com/en-us/azure/bot-service/",
            )
        ],
    )
    return CardFactory.hero_card(card)

diálogos/main_dialog.py

def create_oauth_card(self) -> Attachment:
    card = OAuthCard(
        text="BotFramework OAuth Card",
        connection_name="OAuth connection", # Replace it with the name of your Azure AD connection.
        buttons=[
            CardAction(
                type=ActionTypes.signin,
                title="Sign in",
                value="https://example.org/signin",
            )
        ],
    )
    return CardFactory.oauth_card(card)

Enviar um cartão adaptável

Embora você possa usar a fábrica de mensagens para criar uma mensagem que contenha um anexo (de qualquer tipo), um Adaptive Card é um tipo específico de anexo. Nem todos os canais suportam Adaptive Cards, e alguns canais podem suportar apenas parcialmente Adaptive Cards. Por exemplo, se você enviar um cartão adaptável no Facebook, os botões não funcionarão enquanto os textos e as imagens funcionarem bem. A fábrica de mensagens é uma classe auxiliar do SDK do Bot Framework usada para automatizar as etapas de criação para você.

Os Adaptive Cards são um formato aberto de troca de cartões que permite aos desenvolvedores trocar conteúdo da interface do usuário de forma comum e consistente. No entanto, nem todos os canais suportam Adaptive Cards.

O Adaptive Cards Designer oferece uma experiência de design rica e interativa para a criação de cartões adaptáveis.

Nota

Você deve testar esse recurso com os canais que seu bot usará para determinar se esses canais suportam cartões adaptáveis.

C#

Para usar cartões adaptáveis, certifique-se de adicionar o AdaptiveCards pacote NuGet.

O código-fonte a seguir é do exemplo Usando cartões .

Cartões.cs

Este exemplo lê o JSON do Adaptive Card de um arquivo e o adiciona como um anexo.

public static Attachment CreateAdaptiveCardAttachment()
{
    // combine path for cross platform support
    var paths = new[] { ".", "Resources", "adaptiveCard.json" };
    var adaptiveCardJson = File.ReadAllText(Path.Combine(paths));

    var adaptiveCardAttachment = new Attachment()
    {
        ContentType = "application/vnd.microsoft.card.adaptive",
        Content = JsonConvert.DeserializeObject(adaptiveCardJson),
    };

    return adaptiveCardAttachment;
}

JavaScript

Para usar Adaptive Cards, certifique-se de adicionar o adaptivecards pacote npm.

O código-fonte a seguir é do exemplo Usando cartões .

diálogos/mainDialog.js

Este exemplo lê o JSON do Adaptive Card de um arquivo e cria uma atividade de mensagem com o cartão anexado.

const AdaptiveCard = require('../resources/adaptiveCard.json');

createAdaptiveCard() {
    return CardFactory.adaptiveCard(AdaptiveCard);
}

Java

O código-fonte a seguir é do exemplo Usando cartões .

Cartões.java

Este exemplo lê o JSON do Adaptive Card de um arquivo e o adiciona como um anexo.

public static Attachment createAdaptiveCardAttachment() {
    Attachment adaptiveCardAttachment = new Attachment();

    try (
        InputStream inputStream = adaptiveCardAttachment.getClass().getClassLoader()
        .getResourceAsStream("adaptiveCard.json")
    ) {
        String result = IOUtils.toString(inputStream, StandardCharsets.UTF_8);

        adaptiveCardAttachment.setContentType("application/vnd.microsoft.card.adaptive");
        adaptiveCardAttachment.setContent(new ObjectMapper().readValue(result, ObjectNode.class));

        return adaptiveCardAttachment;
    } catch (Throwable t) {
        throw new CompletionException(t);
    }
}

Python

O código-fonte a seguir é do exemplo Usando cartões .

bots/main_dialog.py

Este exemplo lê o JSON do Adaptive Card de um arquivo e cria uma atividade de mensagem com o cartão anexado.

from .resources.adaptive_card_example import ADAPTIVE_CARD_CONTENT

def create_adaptive_card(self) -> Attachment:
    return CardFactory.adaptive_card(ADAPTIVE_CARD_CONTENT)

Envie um carrossel de cartões

As mensagens também podem incluir vários anexos em um layout de carrossel, que coloca os anexos lado a lado e permite que o usuário role para frente.

C#

O código-fonte a seguir é do exemplo Usando cartões .

Diálogos/MainDialog.cs

Primeiro, crie a resposta e defina os anexos como uma lista.

// Cards are sent as Attachments in the Bot Framework.
// So we need to create a list of attachments for the reply activity.
var attachments = new List<Attachment>();

// Reply to the activity we received with an activity.
var reply = MessageFactory.Attachment(attachments);

Em seguida, adicione os anexos e defina o tipo de layout como carrossel. Aqui estamos a adicioná-los um de cada vez, mas sinta-se à vontade para manipular a lista para adicionar as cartas como preferir.

// Display a carousel of all the rich card types.
reply.AttachmentLayout = AttachmentLayoutTypes.Carousel;
reply.Attachments.Add(Cards.CreateAdaptiveCardAttachment());
reply.Attachments.Add(Cards.GetAnimationCard().ToAttachment());
reply.Attachments.Add(Cards.GetAudioCard().ToAttachment());
reply.Attachments.Add(Cards.GetHeroCard().ToAttachment());
reply.Attachments.Add(Cards.GetOAuthCard().ToAttachment());
reply.Attachments.Add(Cards.GetReceiptCard().ToAttachment());
reply.Attachments.Add(Cards.GetSigninCard().ToAttachment());
reply.Attachments.Add(Cards.GetThumbnailCard().ToAttachment());
reply.Attachments.Add(Cards.GetVideoCard().ToAttachment());

Uma vez que os anexos são adicionados, você pode enviar a resposta como qualquer outro.

// Send the card(s) to the user as an attachment to the activity
await stepContext.Context.SendActivityAsync(reply, cancellationToken);

JavaScript

O código-fonte a seguir é do exemplo Usando cartões .

diálogos/mainDialog.js

Adicione os anexos e defina o tipo de layout como carrossel. Uma vez que os anexos são adicionados, você pode enviar a resposta como qualquer outro.

await stepContext.context.sendActivity({
    attachments: [
        this.createAdaptiveCard(),
        this.createAnimationCard(),
        this.createAudioCard(),
        this.createHeroCard(),
        this.createOAuthCard(),
        this.createReceiptCard(),
        this.createSignInCard(),
        this.createThumbnailCard(),
        this.createVideoCard()
    ],
    attachmentLayout: AttachmentLayoutTypes.Carousel
});

Java

O código-fonte a seguir é do exemplo Usando cartões .

MainDialog.java

Primeiro, crie a resposta e defina os anexos como uma lista.

// Cards are sent as Attachments in the Bot Framework.
// So we need to create a list of attachments for the reply activity.
List<Attachment> attachments = new ArrayList<>();

// Reply to the activity we received with an activity.
Activity reply = MessageFactory.attachment(attachments);

Em seguida, adicione os anexos e defina o tipo de layout como carrossel. Aqui estamos a adicioná-los um de cada vez, mas sinta-se à vontade para manipular a lista para adicionar as cartas como preferir.

// Display a carousel of all the rich card types.
reply.setAttachmentLayout(AttachmentLayoutTypes.CAROUSEL);
reply.getAttachments().add(Cards.createAdaptiveCardAttachment());
reply.getAttachments().add(Cards.getAnimationCard().toAttachment());
reply.getAttachments().add(Cards.getAudioCard().toAttachment());
reply.getAttachments().add(Cards.getHeroCard().toAttachment());
reply.getAttachments().add(Cards.getOAuthCard().toAttachment());
reply.getAttachments().add(Cards.getReceiptCard().toAttachment());
reply.getAttachments().add(Cards.getSigninCard().toAttachment());
reply.getAttachments().add(Cards.getThumbnailCard().toAttachment());
reply.getAttachments().add(Cards.getVideoCard().toAttachment());

Uma vez que os anexos são adicionados, você pode enviar a resposta como qualquer outro.

// Send the card(s) to the user as an attachment to the activity
return stepContext.getContext().sendActivity(reply)

Python

O código-fonte mostrado aqui é baseado no exemplo Usando cartões .

diálogos/main_dialog.py

Primeiro, crie a resposta e defina os anexos como uma lista.

reply = MessageFactory.list([])

Em seguida, adicione os anexos e defina o tipo de layout como carrossel. Aqui estamos a adicioná-los um de cada vez, mas sinta-se à vontade para manipular a lista para adicionar as cartas como preferir.

reply.attachment_layout = AttachmentLayoutTypes.carousel
reply.attachments.append(self.create_adaptive_card())
reply.attachments.append(self.create_animation_card())
reply.attachments.append(self.create_audio_card())
reply.attachments.append(self.create_hero_card())
reply.attachments.append(self.create_oauth_card())
reply.attachments.append(self.create_receipt_card())
reply.attachments.append(self.create_signin_card())
reply.attachments.append(self.create_thumbnail_card())
reply.attachments.append(self.create_video_card())

Uma vez que os anexos são adicionados, você pode enviar a resposta como qualquer outro.

# Send the card(s) to the user as an attachment to the activity
await step_context.context.send_activity(reply)

Exemplo de código para processar a entrada do Adaptive Card

O exemplo a seguir mostra uma maneira de usar entradas de cartão adaptável em uma classe de diálogo de bot. Ele estende a amostra de cartões heróis validando a entrada recebida no campo de texto do cliente respondente. Primeiro, você precisa adicionar a entrada de texto e a funcionalidade de botão ao cartão adaptável existente, adicionando o seguinte código imediatamente antes do colchete final de adaptiveCard.json, localizado na pasta de recursos:

"actions": [
  {
    "type": "Action.ShowCard",
    "title": "Text",
    "card": {
      "type": "AdaptiveCard",
      "body": [
        {
          "type": "Input.Text",
          "id": "text",
          "isMultiline": true,
          "placeholder": "Enter your comment"
        }
      ],
      "actions": [
        {
          "type": "Action.Submit",
          "title": "OK"
        }
      ]
    }
  }
]

O ID do campo de entrada de texto é definido como "texto". Quando o usuário seleciona OK, a mensagem que o Adaptive Card gera terá uma propriedade value que tem uma propriedade nomeada text que contém as informações que o usuário inseriu no campo de entrada de texto do cartão.

C#

Nosso validador usa Newtonsoft.json para primeiro converter isso em um JObjecte, em seguida, criar uma cadeia de texto cortada para comparação. Então adicione:

using System;
using System.Linq;
using Newtonsoft.Json.Linq;

para MainDialog.cs e instale o pacote NuGet estável mais recente do Newtonsoft.Json. No código do validador, adicionamos o fluxo lógico nos comentários do código. Este ChoiceValidator método é colocado no exemplo Usando cartões logo após o público de chave fechada para declaração de MainDialog:

private async Task ChoiceValidator(
    PromptValidatorContext promptContext,
    CancellationToken cancellationToken)
{
    // Retrieves Adaptive Card comment text as JObject.
    // looks for JObject field "text" and converts that input into a trimmed text string.
    var jobject = promptContext.Context.Activity.Value as JObject;
    var jtoken = jobject?["text"];
    var text = jtoken?.Value().Trim();

    // Logic: 1. if succeeded = true, just return promptContext
    //        2. if false, see if JObject contained Adaptive Card input.
    //               No = (bad input) return promptContext
    //               Yes = update Value field with JObject text string, return "true".
    if (!promptContext.Recognized.Succeeded && text != null)
    {
        var choice = promptContext.Options.Choices.FirstOrDefault(
        c => c.Value.Equals(text, StringComparison.InvariantCultureIgnoreCase));
        if (choice != null)
        {
            promptContext.Recognized.Value = new FoundChoice
            {
                Value = choice.Value,
            };
            return true;
        }
    }
    return promptContext.Recognized.Succeeded;
}

Agora acima na alteração da MainDialog declaração:

// Define the main dialog and its related components.
AddDialog(new ChoicePrompt(nameof(ChoicePrompt)));

para:

// Define the main dialog and its related components.
AddDialog(new ChoicePrompt(nameof(ChoicePrompt), ChoiceValidator));

Isso invocará seu validador para procurar a entrada do Adaptive Card cada vez que um novo prompt de escolha for criado.

JavaScript

Abra mainDialog.js e localize o método run Este método async run(turnContext, accessor) lida com a atividade de entrada. Logo após a chamada dialogSet.add(this); , adicione o seguinte:

// The following check looks for a non-existent text input
// plus Adaptive Card input in _activity.value.text
// If both conditions exist, the Activity Card text
// is copied into the text input field.
if(turnContext._activity.text == null
    && turnContext._activity.value.text != null) {
    this.logger.log('replacing null text with Activity Card text input');
    turnContext._activity.text = turnContext._activity.value.text;
  }

Se essa verificação encontrar uma entrada de texto inexistente do cliente, ela verificará se há entrada de um Adaptive Card. Se existir uma entrada do Adaptive Card no _activity.value.text, ele copiará isso para o campo de entrada de texto normal.

Java

Nosso validador usa o auxiliar de serialização de com.microsoft.bot.schema para primeiro convertê-lo em um JsonNodee, em seguida, criar uma cadeia de caracteres de texto cortada para comparação. Também precisaremos de algumas outras importações para concluir isso, então adicione:

import com.fasterxml.jackson.databind.JsonNode;
import com.microsoft.bot.dialogs.prompts.PromptValidator;
import com.microsoft.bot.schema.Serialization;
import java.util.Optional;
import org.apache.commons.lang3.StringUtils;

para MainDialog.java. No código do validador, adicionamos o fluxo lógico nos comentários do código. Esta PromptValidator expressão é colocada no exemplo Usando cartões logo após o público de chaves fechadas para declaração de MainDialog:

PromptValidator<FoundChoice> validator = (promptContext) -> {
    // Retrieves Adaptive Card comment text as JObject.
    // looks for JObject field "text" and converts that input into a trimmed text
    // string.
    JsonNode jsonNode = Serialization.getAs(promptContext.getContext().getActivity().getValue(), JsonNode.class);
    JsonNode textNode = jsonNode != null ? jsonNode.get("text") : null;
    String text = textNode != null ? textNode.textValue() : "";

    // Logic: 1. if succeeded = true, just return promptContext
    // 2. if false, see if JObject contained Adaptive Card input.
    // No = (bad input) return promptContext
    // Yes = update Value field with JObject text string, return "true".
    if (!promptContext.getRecognized().getSucceeded() && text != null) {
        Optional<Choice> choice = promptContext.getOptions()
            .getChoices()
            .stream()
            .filter(c -> StringUtils.compareIgnoreCase(c.getValue(), text) == 0)
            .findFirst();

        if (choice.isPresent()) {
            promptContext.getRecognized().setValue(new FoundChoice() {
                {
                    setValue(choice.get().getValue());
                }
            });
            return CompletableFuture.completedFuture(true);
        }
    }
    return CompletableFuture.completedFuture(promptContext.getRecognized().getSucceeded());
};

Agora acima na alteração da MainDialog declaração:

// Define the main dialog and its related components.
addDialog(new ChoicePrompt("ChoicePrompt"));

para:

// Define the main dialog and its related components.
addDialog(new ChoicePrompt("ChoicePrompt", validator, null));

Isso invocará seu validador para procurar a entrada do Adaptive Card cada vez que um novo prompt de escolha for criado.

Python

Crie e envie uma atividade com ações sugeridas para o usuário.

Este choice_validator método é colocado na amostra Usando cartões logo após o público de chave fechada para declaração de MainDialog:

@staticmethod
async def choice_validator(prompt_context: PromptValidatorContext) -> bool:
    if prompt_context.context.activity.value:
        text = prompt_context.context.activity.value["text"].lower()
        if not prompt_context.recognized.succeeded and text:
            matching_choices = [choice for choice in prompt_context.options.choices if choice.value.lower() == text]
            if matching_choices:
                choice = matching_choices[0]
                prompt_context.recognized.value = FoundChoice(
                    value=choice.value,
                    index=0,
                    score=1.0
                )
                return True

    return prompt_context.recognized.succeeded

Agora acima na alteração da MainDialog declaração:

self.add_dialog(ChoicePrompt(CARD_PROMPT))

para:

self.add_dialog(ChoicePrompt(CARD_PROMPT, MainDialog.choice_validator))

Isso invocará seu validador para procurar a entrada do Adaptive Card cada vez que um novo prompt de escolha for criado.

Testar o bot Usando cartões

1. Execute o exemplo Usando cartões localmente e abra o bot no Emulador do Bot Framework.
2. Siga as instruções no bot para exibir um tipo de cartão, como um Adaptive Card.

Próximos passos

Adicionar botões para orientar a ação do usuário