Bot Framework SDK'sı ile medya ekleri gönderme

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Kullanıcı ve bot arasında alışveriş yapılan iletiler görüntü, video, ses ve dosyalar gibi medya ekleri içerebilir. Bot Framework SDK'sı, kullanıcıya zengin iletiler gönderme görevini destekler. Bir kanalın (Facebook, Slack vb.) desteklediği zengin iletilerin türünü belirlemek için sınırlamalar hakkında bilgi için kanalın belgelerine bakın.

Not

Bot Framework JavaScript, C# ve Python SDK'ları desteklenmeye devam edecektir, ancak Java SDK'sı son uzun vadeli destek Kasım 2023'te sona erecek şekilde kullanımdan kaldırılacaktır.

Java SDK ile oluşturulan mevcut botlar çalışmaya devam edecektir.

Yeni bot derlemesi için Power Virtual Agents'ı kullanmayı göz önünde bulundurun ve doğru sohbet botu çözümünü seçme hakkında bilgi edinin.

Daha fazla bilgi için bkz . Bot oluşturmanın geleceği.

Önkoşullar

• Botun temelleri hakkında bilgi.
• Bu makaledeki kod aşağıdaki örnekleri temel alır:
  • Kartları kullanma: C#, JavaScript, Java, Python
  • Ekleri işleme: C#, JavaScript, Java, Python
  • Önerilen eylemler: C#, JavaScript, Java, Python

Ekleri gönderme

Kullanıcıya resim veya video gibi içerik göndermek için iletiye ek veya ek listesi ekleyebilirsiniz.

Kullanılabilir kart örnekleri için bkz . Kullanıcı deneyimini tasarlama.

Ayrıca SSS bölümünde kanallar kullanılarak aktarılan bir dosyanın boyut sınırı nedir? konusuna bakın.

C#

Bu bölümde gösterilen tüm kaynak kodu, Ekleri işleme örneğini temel alır .

Attachments nesnesinin özelliği, iletiye Activity eklenen medya eklerini ve zengin kartları temsil eden bir nesne dizisi Attachment içerir. İletiye medya eki eklemek için etkinlik için bir Attachment nesne oluşturun ve , ContentUrlve Name özelliklerini ayarlayınContentType.reply

Yanıt iletisini oluşturmak için metni tanımlayın ve ekleri ayarlayın. Eklerin yanıta atanma işlemi her ek türü için aynıdır, ancak aşağıdaki kod parçacıklarında görüldüğü gibi çeşitli ekler farklı şekilde ayarlanır ve tanımlanır. Aşağıdaki kod, satır içi ek için yanıtı ayarlanıyor:

Botlar/AttachmentsBot.cs

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

Ardından, ek türlerine bakacağız. İlki satır içi ektir:

Botlar/AttachmentsBot.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}",
    };
}

Ardından karşıya yüklenen bir ek:

Botlar/AttachmentsBot.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,
    };
}

Son olarak, bir internet eki:

Botlar/AttachmentsBot.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

Aşağıdaki kaynak kodu Ekleri işleme örneğinden alınmalıdır .

Ekleri kullanmak için botunuza aşağıdaki kitaplıkları ekleyin:

botlar/attachmentsBot.js

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

Yanıt iletisini oluşturmak için metni tanımlayın ve ekleri ayarlayın. Eklerin yanıta atanma işlemi her ek türü için aynıdır, ancak aşağıdaki kod parçacıklarında görüldüğü gibi çeşitli ekler farklı şekilde ayarlanır ve tanımlanır. Aşağıdaki kod, satır içi ek için yanıtı ayarlanıyor:

botlar/attachmentsBot.js

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

Kullanıcıya resim veya video gibi tek bir içerik göndermek için medyayı birkaç farklı yolla gönderebilirsiniz. İlk olarak, satır içi ek olarak:

botlar/attachmentsBot.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 }`
    };
}

Ardından karşıya yüklenen bir ek:

botlar/attachmentsBot.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
    };

Son olarak, URL'de bulunan bir internet eki:

botlar/attachmentsBot.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

Bu bölümde gösterilen kaynak kodu, Ekleri işleme örneğini temel alır .

getAttachments() nesnesinin Activity yöntemi, medya eklerini ve iletiye eklenmiş zengin kartları temsil eden bir nesne dizisi Attachment içerir. İletiye medya eki eklemek için etkinlik için bir Attachment nesne oluşturun ve , ContentUrlve Name özelliklerini ayarlayınContentType.reply

Yanıt iletisini oluşturmak için metni tanımlayın ve ekleri ayarlayın. Eklerin yanıta atanma işlemi her ek türü için aynıdır, ancak aşağıdaki kod parçacıklarında görüldüğü gibi çeşitli ekler farklı şekilde ayarlanır ve tanımlanır. Aşağıdaki kod, satır içi ek için yanıtı ayarlanıyor:

AttachmentsBot.java

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

Ardından, ek türlerine bakacağız. İlki satır içi ektir:

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

Ardından karşıya yüklenen bir ek:

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

Son olarak, bir internet eki:

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

Aşağıdaki kaynak kodu Ekleri işleme örneğinden alınmalıdır .

Yanıt iletisini oluşturmak için metni tanımlayın ve ekleri ayarlayın. Eklerin yanıta atanma işlemi her ek türü için aynıdır, ancak aşağıdaki kod parçacıklarında görüldüğü gibi çeşitli ekler farklı şekilde ayarlanır ve tanımlanır.

Aşağıdaki kod, satır içi ek için yanıtı ayarlanıyor:

botlar/attachments_bot.py

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

Kullanıcıya resim veya video gibi tek bir içerik göndermek için medyayı birkaç farklı yolla gönderebilirsiniz. İlk olarak, satır içi ek olarak:

botlar/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}",
    )

Ardından karşıya yüklenen bir ek:

botlar/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,
    )

Son olarak, URL'de bulunan bir internet eki:

botlar/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",
    )

Ek bir görüntü, ses veya videoysa, Bağlan veya hizmeti ek verilerini kanala, kanalın bu eki konuşma içinde işlemesini sağlayacak şekilde iletir. Ek bir dosyaysa, dosya URL'si konuşmanın içinde köprü olarak işlenir.

Kahraman kartı gönderme

Basit görüntü veya video eklerinin yanı sıra, görüntüleri ve düğmeleri tek bir nesnede birleştirmenizi ve kullanıcıya göndermenizi sağlayan bir hero kartı ekleyebilirsiniz. Markdown çoğu metin alanında desteklenir, ancak destek kanala göre farklılık gösterebilir.

C#

Hero kartı ve düğmesiyle ileti oluşturmak için, iletiye nesne HeroCard ekleyebilirsiniz.

Aşağıdaki kaynak kodu Ekleri işleme örneğinden alınmalıdır .

Botlar/AttachmentsBot.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

Hero kartı ve düğmesiyle ileti oluşturmak için, iletiye nesne HeroCard ekleyebilirsiniz.

Aşağıdaki kaynak kodu Ekleri işleme örneğinden alınmalıdır .

botlar/attachmentsBot.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

Hero kartı ve düğmesiyle ileti oluşturmak için, iletiye nesne HeroCard ekleyebilirsiniz.

Aşağıdaki kaynak kodu Ekleri işleme örneğinden alınmalıdır .

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

Hero kartı ve düğmesiyle ileti oluşturmak için, iletiye nesne HeroCard ekleyebilirsiniz.

Aşağıdaki kaynak kodu Ekleri işleme örneğinden alınmalıdır .

botlar/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"
            ),
        ],
    )

Zengin kartlarda olayları işleme

Zengin kartlar içindeki olayları işlemek için, kullanıcı bir düğme seçtiğinde veya kartın bir bölümüne dokunduğunda ne olacağını belirtmek için kart eylem nesnelerini kullanın. Her kart eyleminin bir tür ve değer özelliği vardır.

Düzgün çalışması için, bir hero kartındaki her tıklanabilir öğeye bir eylem türü atayın. Bu tabloda kullanılabilir eylem türleri ve ilişkili değer özelliğinde olması gerekenler listelenip açıklanmaktadır. Kart messageBack eylemi, diğer kart eylemlerinden daha genelleştirilmiş bir anlama sahiptir. ve diğer kart eylem türleri hakkında daha fazla bilgi için Etkinlik şemasınınmessageBack Kart eylemi bölümüne bakın.

Type	Açıklama	Değer
call	Bir telefon araması başlatır.	Telefon aramasının hedefi şu biçimdedir: tel:123123123123.
Downloadfile	Bir dosya indirir.	İndirilmesi gereken dosyanın URL'si.
imBack	Bota bir ileti gönderir ve sohbette görünür bir yanıt gönderir.	Gönderilecek iletinin metni.
messageBack	Sohbet sistemi aracılığıyla gönderilecek metin yanıtını temsil eder.	Oluşturulan iletilere eklenecek isteğe bağlı bir program değeri.
Openurl	Yerleşik tarayıcıda bir URL açar.	Açılacak URL.
playAudio	Ses çalar.	Yürütülecek sesin URL'si.
playVideo	Video yürütülür.	Yürütülecek videonun URL'si.
Geri gönderme	Bota bir ileti gönderir ve sohbette görünür bir yanıt göndermeyebilir.	Gönderilecek iletinin metni.
showImage	Bir resim görüntüler.	Görüntülenecek görüntünün URL'si.
Imzalıyorum	OAuth oturum açma işlemini başlatır.	Başlatacak OAuth akışının URL'si.

Çeşitli olay türlerini kullanan Hero kartı

Aşağıdaki kod çeşitli zengin kart olaylarını kullanan örnekleri gösterir.

C#

Kullanılabilir tüm kartlar için bkz . Kartları kullanma örneği.

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

Cards.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

Kullanılabilir tüm kartlar için bkz . Kartları kullanma örneği.

iletişim kutuları/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/'
            }
        ])
    );
}

iletişim kutuları/mainDialog.js

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

Java

Kullanılabilir tüm kartlar için bkz . Kartları kullanma örneği.

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

Cards.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

Kullanılabilir tüm kartlar için bkz . Kartları kullanma örneği.

iletişim kutuları/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)

iletişim kutuları/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)

Uyarlamalı Kart Gönderme

İleti fabrikasını kullanarak ek içeren bir ileti (herhangi bir türde) oluşturabilirsiniz ancak Uyarlamalı Kart belirli bir ek türüdür. Tüm kanallar Uyarlamalı Kartları desteklemez ve bazı kanallar Uyarlamalı Kartları yalnızca kısmen destekleyemeyebilir. Örneğin, Facebook'ta Uyarlamalı Kart gönderirseniz, metinler ve resimler düzgün çalışırken düğmeler çalışmaz. İleti fabrikası, oluşturma adımlarını sizin için otomatikleştirmek için kullanılan bir Bot Framework SDK yardımcı sınıfıdır.

Uyarlamalı Kartlar, geliştiricilerin kullanıcı arabirimi içeriğini ortak ve tutarlı bir şekilde paylaşmalarını sağlayan açık bir kart değişim biçimidir. Ancak, tüm kanallar Uyarlamalı Kartları desteklemez.

Uyarlamalı Kartlar Tasarım Aracı, uyarlamalı kartlar yazmak için zengin, etkileşimli bir tasarım zamanı deneyimi sağlar.

Not

Bu özelliği botunuzun uyarlamalı kartları destekleyip desteklemediğini belirlemek için botunuzun kullanacağı kanallarla test etmelisiniz.

C#

Uyarlamalı Kartlar'ı kullanmak için NuGet paketini eklediğinizden AdaptiveCards emin olun.

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

Cards.cs

Bu örnek, uyarlamalı kart JSON dosyasını bir dosyadan okur ve ek olarak ekler.

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

Uyarlamalı Kartlar'ı kullanmak için npm paketini eklediğinizden adaptivecards emin olun.

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

iletişim kutuları/mainDialog.js

Bu örnek, bir dosyadan Uyarlamalı Kart JSON dosyasını okur ve kartın eklendiği bir ileti etkinliği oluşturur.

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

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

Java

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

Cards.java

Bu örnek, uyarlamalı kart JSON dosyasını bir dosyadan okur ve ek olarak ekler.

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

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

botlar/main_dialog.py

Bu örnek, bir dosyadan Uyarlamalı Kart JSON dosyasını okur ve kartın eklendiği bir ileti etkinliği oluşturur.

from .resources.adaptive_card_example import ADAPTIVE_CARD_CONTENT

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

Kartlardan oluşan bir döngü gönderme

İletiler, döngü düzeninde ekleri yan yana yerleştiren ve kullanıcının kaydırma yapmasına olanak tanıyan birden çok ek de içerebilir.

C#

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

İletişim Kutuları/MainDialog.cs

İlk olarak yanıtı oluşturun ve ekleri liste olarak tanımlayın.

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

Ardından ekleri ekleyin ve düzen türünü döngü olarak ayarlayın. Burada bunları birer birer ekliyoruz, ancak istediğiniz gibi kartları eklemek için listeyi değiştirmekte çekinmeyin.

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

Ekler eklendikten sonra, yanıtı diğer tüm yanıtlar gibi gönderebilirsiniz.

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

JavaScript

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

iletişim kutuları/mainDialog.js

Ekleri ekleyin ve düzen türünü döngü olarak ayarlayın. Ekler eklendikten sonra, yanıtı diğer tüm yanıtlar gibi gönderebilirsiniz.

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

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

MainDialog.java

İlk olarak yanıtı oluşturun ve ekleri liste olarak tanımlayın.

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

Ardından ekleri ekleyin ve düzen türünü döngü olarak ayarlayın. Burada bunları birer birer ekliyoruz, ancak istediğiniz gibi kartları eklemek için listeyi değiştirmekte çekinmeyin.

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

Ekler eklendikten sonra, yanıtı diğer tüm yanıtlar gibi gönderebilirsiniz.

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

Python

Burada gösterilen kaynak kodu, Kart kullanma örneğini temel alır.

iletişim kutuları/main_dialog.py

İlk olarak yanıtı oluşturun ve ekleri liste olarak tanımlayın.

reply = MessageFactory.list([])

Ardından ekleri ekleyin ve düzen türünü döngü olarak ayarlayın. Burada bunları birer birer ekliyoruz, ancak istediğiniz gibi kartları eklemek için listeyi değiştirmekte çekinmeyin.

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

Ekler eklendikten sonra, yanıtı diğer tüm yanıtlar gibi gönderebilirsiniz.

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

Uyarlamalı Kart girişini işlemek için kod örneği

Aşağıdaki örnekte, bot iletişim kutusunda Uyarlamalı Kart girişlerini kullanmanın bir yolu gösterilmektedir. Yanıtlayan istemciden metin alanında alınan girişi doğrulayarak hero kartları örneğini genişletir. İlk olarak, kaynaklar klasöründe bulunan adaptiveCard.json son köşeli ayracından hemen önce aşağıdaki kodu ekleyerek var olan uyarlamalı karta metin girişi ve düğme işlevselliğini eklemeniz gerekir:

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

Metin giriş alanının kimliği "text" olarak ayarlanır. Kullanıcı Tamam'ı seçtiğinde, Uyarlamalı Kart'ın oluşturduğu ileti, kullanıcının kartın metin girişi alanına girdiği bilgileri içeren adlı text bir özelliğe sahip bir değer özelliğine sahip olur.

C#

Doğrulayıcımız bunu önce öğesine JObjectdönüştürmek için Newtonsoft.json kullanır ve ardından karşılaştırma için kırpılmış bir metin dizesi oluşturur. Bu nedenle ekleyin:

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

MainDialog.cs ve Newtonsoft.Json'un en son kararlı NuGet paketini yüklemek için. Doğrulayıcı kodunda, kod açıklamalarına mantıksal akışı ekledik. Bu ChoiceValidator yöntem MainDialog bildirimi için kapalı küme ayracı genelinin hemen ardından Using cards örneğine yerleştirilir:

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

Bildirim değişikliğinde MainDialog şimdi yukarıda:

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

yerine şunu yazın:

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

Bu, her yeni seçenek istemi oluşturulduğunda Uyarlamalı Kart girişini aramak için doğrulayıcınızı çağırır.

JavaScript

mainDialog.js açın ve bu yöntem gelen etkinliği işler çalıştırma yöntemini async run(turnContext, accessor) bulun. Aramadan dialogSet.add(this); hemen sonra aşağıdakileri ekleyin:

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

Bu denetim istemciden varolmayan bir metin girişi bulursa Uyarlamalı Kart'tan giriş olup olmadığını görür. konumunda _activity.value.textuyarlamalı kart girişi varsa, bunu normal metin girişi alanına kopyalar.

Java

Doğrulayıcımız bunu önce öğesine dönüştürmek JsonNodeiçin com.microsoft.bot.schema adresindeki Serileştirme yardımcısını kullanır ve ardından karşılaştırma için kırpılmış bir metin dizesi oluşturur. Bunu tamamlamak için birkaç içeri aktarma işlemi daha gerekir, bu nedenle şunları ekleyin:

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;

MainDialog.java. Doğrulayıcı kodunda, kod açıklamalarına mantıksal akışı ekledik. Bu PromptValidator ifade MainDialog bildirimi için kapalı küme ayracı genelinin hemen ardından Using cards örneğine yerleştirilir:

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

Bildirim değişikliğinde MainDialog şimdi yukarıda:

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

yerine şunu yazın:

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

Bu, her yeni seçenek istemi oluşturulduğunda Uyarlamalı Kart girişini aramak için doğrulayıcınızı çağırır.

Python

Kullanıcıya önerilen eylemleri içeren bir etkinlik oluşturun ve gönderin.

Bu choice_validator yöntem, bildirimi için MainDialogkapalı küme ayracı genelinin hemen ardından Using cards örneğine yerleştirilir:

@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

Bildirim değişikliğinde MainDialog şimdi yukarıda:

self.add_dialog(ChoicePrompt(CARD_PROMPT))

yerine şunu yazın:

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

Bu, her yeni seçenek istemi oluşturulduğunda Uyarlamalı Kart girişini aramak için doğrulayıcınızı çağırır.

Kart Kullanma botunu test edin

1. Kart kullanma örneğini yerel olarak çalıştırın ve botu Bot Framework Öykünücüsü'nde açın.
2. Uyarlamalı Kart gibi bir kart türünü görüntülemek için bottaki istemleri izleyin.

Sonraki adımlar

Kullanıcı eylemine kılavuzluk etmek için düğme ekleme