แชร์ผ่าน

ถามโดยใช้ Adaptive Cards

Adaptive Cards ช่วยให้คุณสามารถเพิ่มส่วนย่อยของเนื้อหาให้กับตัวแทน Copilot Studio ที่สามารถแลกเปลี่ยนอย่างเปิดเผยกับแอปและบริการคลาวด์อื่นๆ ได้ คุณสามารถใส่ข้อความ กราฟิก และปุ่มต่างๆ เพื่อมอบความสามารถในการสนทนาที่หลากหลายให้กับเอเจนต์ของคุณ เนื่องจากไม่ขึ้นอยู่กับแพลตฟอร์ม คุณสามารถปรับแต่ง Adaptive Cards ตามความต้องการของคุณได้อย่างง่ายดาย

ด้วยโหนด การ์ดที่ปรับเปลี่ยนได้ เอเจนต์ของคุณสามารถแสดงการ์ดที่ปรับเปลี่ยนได้ที่มีปุ่มส่งตั้งแต่หนึ่งปุ่มขึ้นไป และสามารถเลือกฟิลด์ป้อนข้อมูลฟอร์มอย่างน้อยหนึ่งฟิลด์ เอเจนต์ของคุณจัดเก็บข้อมูลที่ผู้ใช้ป้อนไว้ในตัวแปรเพื่อใช้ในภายหลังในการสนทนา

หมายเหตุ

Copilot Studio สนับสนุน schema Adaptive Cards เวอร์ชัน 1.6 และเวอร์ชันก่อนหน้า อย่างไรก็ตาม รุ่น Schema ที่เหมาะสมขึ้นอยู่กับแอปโฮสต์เป้าหมาย:

  • คอมโพเนนต์ Web Chat Bot Framework (นั่นคือ รูปแบบการรวมเว็บไซต์เริ่มต้น) สนับสนุนเวอร์ชัน 1.6 แต่ไม่สนับสนุน Action.Execute
  • วิดเจ็ตแชทสด (ใช้สําหรับ Dynamics 365 Omnichannel สําหรับฝ่ายบริการลูกค้า) จํากัดเฉพาะเวอร์ชัน 1.5
  • Teams ยังถูกจำกัดไว้ที่เวอร์ชัน 1.5

นอกจากนี้ Copilot Studio จะแสดงการ์ดเวอร์ชัน 1.6 ในการสนทนาทดสอบเท่านั้น ไม่ใช่บนพื้นที่ทํางาน

สําหรับข้อมูลเพิ่มเติมเกี่ยวกับ schema ของ Adaptive Cards ดูที่ Schema Explorer

Copilot Studio มีตัวออกแบบอะแดปทีฟการ์ดในตัว ซึ่งมีคุณสมบัติที่มีประโยชน์ที่สุดจากตัวออกแบบอะแดปทีฟการ์ด

หรือคุณสามารถ:

  • ใช้การแสดง JSON สำหรับการ์ดที่คุณต้องการแสดงต่อผู้ใช้
  • ใช้ สูตร Power Fx เพื่อรวมข้อมูลแบบไดนามิกไว้บนการ์ด

คุณยังสามารถควบคุมลักษณะการทำงานของการ์ด เช่น จะทำอย่างไรเมื่อผู้ใช้ป้อนคำตอบที่ไม่ถูกต้องหรือหากโหนดไม่สามารถขัดจังหวะได้

โหนด การ์ดที่ปรับเปลี่ยนได้ มีไว้สำหรับการ์ดแบบโต้ตอบซึ่งคาดว่าผู้ใช้จะส่งการตอบกลับ ใช้โหนด ข้อความ และ คําถาม เพื่อแสดงผู้ใช้ที่มีการ์ดที่ไม่ใช่การ์ดแบบโต้ตอบที่แสดงข้อมูล

เคล็ดลับ

เปลี่ยนชื่อโหนดเพื่อให้สามารถระบุได้ง่ายขึ้น เลือกช่องชื่อโหนดเพื่ออัปเดตชื่อโดยตรง หรือเลือกจุดสามจุด (...) ของโหนด แล้วเลือกเปลี่ยน ชื่อ จากเมนู นอกจากนี้คุณยังสามารถเปลี่ยนชื่อโหนดใน ตัวแก้ไขโค้ด

ไม่สามารถเปลี่ยนชื่อโหนด ทริกเกอร์ และโหนด ไปที่ขั้นตอน ได้

ชื่อโหนดสามารถมีความยาวได้สูงสุด 500 อักขระ

โหนดเพิ่มการ์ดที่ปรับเปลี่ยนได้

  1. เลือกไอคอน เพิ่มโหนด ภายใต้โหนดที่คุณต้องการเพิ่มโหนดอะแดปทีฟการ์ด จากนั้นเลือก ถามด้วยอะแดปทีฟการ์ด

  2. เลือกจุดสามจุด (...) ของโหนด แล้วเลือก คุณสมบัติ

  3. ในแผง คุณสมบัติของโหนดการ์ดที่ปรับเปลี่ยนได้ ให้เลือก แก้ไขการ์ดที่ปรับเปลี่ยนได้ แผงตัวออกแบบการ์ดที่ปรับเปลี่ยนได้จะเปิดขึ้น

  4. เพิ่มองค์ประกอบที่ต้องการสำหรับการ์ดของคุณและกำหนดค่าคุณสมบัติ หรือในบานหน้าต่าง ตัวแก้ไขส่วนข้อมูลของการ์ด แทนที่ส่วนข้อมูลเริ่มต้นด้วยสัญพจน์ JSON สำหรับการ์ดของคุณ

    เคล็ดลับ

    การ์ดของคุณต้องมีปุ่มส่งอย่างน้อยหนึ่งปุ่ม เนื่องจากต้องเป็นการ์ดแบบโต้ตอบที่อนุญาตให้ผู้ใช้ส่งข้อมูลกลับไปยังเอเจนต์ หากไม่มีและมีวัตถุประสงค์เพื่อแสดงข้อมูลเท่านั้น คุณควรเพิ่มการ์ดที่ปรับเปลี่ยนได้ของคุณไปยังโหนดข้อความ

  5. เมื่อคุณออกแบบแรกเสร็จแล้ว ให้เลือก บันทึก และปิดแผงตัวออกแบบ ตัวอย่างการ์ดของคุณจะปรากฏบนโหนด Copilot Studio จะสร้างตัวแปรเอาต์พุตตามอินพุตที่ระบุไว้ในโค้ดโดยอัตโนมัติ

    ภาพหน้าจอของโหนดการ์ดที่ปรับเปลี่ยนได้พร้อมการแสดงตัวอย่างของการ์ด

    เคล็ดลับ

    หากตัวแปรเอาต์พุตที่สร้างขึ้นสำหรับการ์ดของคุณไม่ถูกต้อง คุณสามารถอัปเดตรายการตัวแปรและชนิดด้วยตนเองได้โดยเลือก แก้ไข Schema ในแผง คุณสมบัติของโหนดการ์ดที่ปรับเปลี่ยนได้

    อะแดปทีฟการ์ดแบบโต้ตอบของคุณพร้อมใช้งานแล้ว เมื่อผู้ใช้เอเจนต์ของคุณเลือกปุ่มส่งบนการ์ด ตัวแปรเอาต์พุตจะถูกเติมด้วยข้อมูลที่ผู้ใช้ให้ไว้ในการโต้ตอบกับการ์ด

คุณสมบัติอื่นๆ

คุณสามารถใช้คุณสมบัติอื่น ๆ เพื่อควบคุมลักษณะการทํางานของโหนด อะแดปทีฟการ์ด เช่น:

  • วิธีที่เอเจนต์ตอบสนองต่อการตอบกลับที่ไม่ถูกต้อง
  • หากสามารถขัดจังหวะได้

หากเอเจนต์กำลังรอการส่งจากการ์ดที่ปรับเปลี่ยนได้ และผู้ใช้ส่งข้อความแทน การตอบกลับนี้จะถือว่าไม่ถูกต้องเว้นแต่ข้อความจะทำให้เกิดการหยุดชะงัก ในกรณีนี้ คุณสมบัติต่อไปนี้จะกำหนดลักษณะการทำงาน

  • จำนวนครั้งที่การขอให้ตอบกลับอีกครั้ง: จำนวนครั้งที่เอเจนต์ของคุณพยายามได้รับคำตอบที่ถูกต้องจากการ์ด ค่าเริ่มต้นคือ ทําซ้ําสูงสุด 2 ครั้ง คุณยังสามารถเลือก ทำซ้ำหนึ่งครั้ง หรือ ไม่ทำซ้ำ สำหรับการลองใหม่แต่ละครั้ง การ์ดจะถูกส่งไปยังผู้ใช้อีกครั้ง

  • พร้อมท์ลองอีกครั้ง: ใช้คุณสมบัตินี้เพื่อกําหนดข้อความที่จะส่งเมื่อมีการลองใหม่ พร้อมกับการทําซ้ําของการ์ด เมื่อต้องการกําหนดข้อความลองใหม่ ให้เลือก กําหนดเอง แล้วใส่พร้อมท์ใหม่

  • อนุญาตให้สลับไปยังหัวข้ออื่น: หากเลือก (ค่าเริ่มต้น) ข้อความขาเข้าจากผู้ใช้เมื่อเอเจนต์กำลังรอการส่งการ์ดจะทำให้เกิดการหยุดชะงักและสลับไปยังหัวข้ออื่น หากมีการสลับหัวข้อเกิดขึ้นการ์ดจะถูกส่งไปยังผู้ใช้อีกครั้งเมื่อหัวข้อที่ขัดจังหวะสิ้นสุดลง

ลักษณะการทํางานของปุ่มส่งสําหรับเอเจนต์ที่มีการ์ดติดต่อกัน

ตามการออกแบบ Adaptive Cards อนุญาตให้เลือกปุ่มส่งหลายครั้ง หากเอเจนต์มี Adaptive Cards ติดต่อกัน และผู้ใช้เลือกปุ่มบนการ์ดก่อนหน้านี้ ผู้ใช้อาจพบลักษณะการทํางานที่ไม่คาดคิด

เพื่อป้องกันไม่ให้การดำเนินการส่งบนการ์ดหนึ่งรบกวนการ์ดอื่น:

  • แยกการดำเนินการส่ง: ตรวจสอบว่าการ์ดที่ปรับเปลี่ยนได้แต่ละใบมีตัวระบุที่ไม่ซ้ำกันและตัวจัดการการดำเนินการของตนเอง

  • ใช้การดําเนินการส่งพร้อมข้อมูลที่ไม่ซ้ํากัน: เมื่อคุณกําหนดการดําเนินการส่งสําหรับการ์ดของคุณ รวมถึงตัวระบุที่ไม่ซ้ํากันหรือส่วนข้อมูลเพื่อช่วยแยกความแตกต่างระหว่างการ์ดเมื่อผู้ใช้เลือกปุ่มส่ง

  • เพิ่มตรรกะการจัดการเหตุการณ์ที่มีประสิทธิภาพให้กับเอเจนต์ของคุณ: กำหนดเงื่อนไขตามองค์ประกอบตัวระบุหรือส่วนข้อมูลที่โดดเด่นที่เชื่อมโยงกับปุ่มส่งของคุณ

  • แก้จุดบกพร่องและบันทึก: เพิ่มการบันทึกโดยละเอียดลงในโค้ดการจัดการเหตุการณ์ของเอเจนต์ของคุณเพื่อจับลำดับการดำเนินการและระบุตำแหน่งที่มีการส่งที่ไม่ได้ตั้งใจเกิดขึ้น

ใช้ตัวระบุการส่งใน Action.Submit data

ถ้าตัวแทนของคุณส่งอะแดปทีฟการ์ดหลายใบในการสนทนา (ตัวอย่างเช่น การ์ดติดต่อกัน ลองใหม่ หรือหยุดชะงัก) ผู้ใช้อาจเลือก ส่ง บนการ์ดก่อนหน้า เพื่อช่วยให้ตัวแทนหรือลูกค้าแบบกำหนดเองแยกความแตกต่างของการ์ดและการดำเนินการที่การตอบสนองมาจากไหน ให้รวมถึงตัวระบุเฉพาะใน payload ของข้อมูลของแต่ละการดำเนินการส่งและยืนยันความถูกต้องเมื่อประมวลผลการตอบสนอง

ตัวอย่าง:

{
  "type": "Action.Submit",
  "title": "Confirm",
  "data": {
    "actionSubmitId": "booking_confirm_card_v3_confirm"
  }
}

เคล็ดลับการใช้งาน Web Chat UX เพื่อหลีกเลี่ยงการคลิกที่ไม่ทันสมัย

โปรแกรมแชทบางโปรแกรม รวมถึงเวอร์ชันเว็บ อาจอนุญาตให้การ์ดก่อนหน้านี้ยังคงคลิกได้หลังจากที่ผู้ใช้ส่งการ์ดใบสุดท้าย หากคุณสร้างประสบการณ์การแชทบนเว็บที่กําหนดเองให้พิจารณาปิดใช้งานปุ่มส่งหลังจากคลิกครั้งแรกหรืออัปเดตข้อความการ์ดก่อนหน้าเพื่อลดการส่งซ้ําซ้อนโดยไม่ตั้งใจหรือเก่า

ตัวอย่างต่อไปนี้แสดงหนึ่งในวิธีในการปิดใช้งาน Action.Submit buttons หลังจากการคลิกครั้งแรกในประสบการณ์การสนทนาบนเว็บแบบกําหนดเอง:

  1. แสดงอะแดปทีฟการ์ดโดยใช้ SDK ของอะแดปทีฟการ์ดหรือการแสดงผลอื่นที่สร้างปุ่ม HTML หรืออินพุตจริง

  2. เมื่อคุณได้รับคำสั่งการส่ง ให้ทําเครื่องหมายการ์ดที่ใช้อยู่ในขณะนั้นว่าเป็นการส่งใน UI ของคุณทันที ตัวอย่างเช่น ตั้งค่าสถานะ submitted ให้กับข้อความ

  3. ทำการเรนเดอร์ใหม่หรือเปลี่ยนแปลง Document Object Model (DOM) ของการ์ด เพื่อให้องค์ประกอบแบบโต้ตอบทั้งหมดถูกปิดใช้งาน จากนั้นส่งข้อมูลที่เตรียมส่งไปยังบอทหรือบริการของคุณ

  4. หากแชทของคุณรองรับหลายการ์ดต่อการสนทนา ให้ทําซ้ํารูปแบบเดียวกันสําหรับข้อความการ์ดทุกข้อความเพื่อป้องกันไม่ให้การส่งเก่าจากการ์ดเก่า

ตัวอย่าง:

// Example: disable Adaptive Card submit interactions after the first click.
// This is UI-side logic for custom web chat experiences.

// When you render a card, keep a reference to its container element.
// For example, each chat message could render into its own <div>.
function disableCardInteractivity(cardContainer) {
    // Disable buttons (including Action.Submit rendered as <button>).
    for (const el of cardContainer.querySelectorAll('button, input, select, textarea')) {
        el.disabled = true;
        el.setAttribute('aria-disabled', 'true');
    }

    // Optional: prevent click handlers from firing (defense-in-depth).
    cardContainer.addEventListener(
        'click',
        (evt) => {
            const target = /** @type {HTMLElement} */ (evt.target);
            if (target && target.closest && target.closest('button, input, select, textarea')) {
                evt.preventDefault();
                evt.stopPropagation();
            }
        },
        true
    );
}

// Wire the behavior into your Adaptive Cards host.
// The Adaptive Cards SDK surfaces submits via onExecuteAction.
function wireCardSubmitHandling(adaptiveCard, cardContainer, sendToBot) {
    let submitted = false;

    adaptiveCard.onExecuteAction = async (action) => {
        // Only allow the first submit from this card instance.
        if (submitted) {
            return;
        }
        submitted = true;

        // Disable the UI immediately to avoid duplicate/stale clicks.
        disableCardInteractivity(cardContainer);

        // Send the submit payload to your bot/service.
        // If you're using Action.Submit with a unique ID (for example, actionSubmitId),
        // include it in the payload so your bot can de-duplicate safely.
        await sendToBot({
            type: 'adaptiveCard/submit',
            data: action && action.data ? action.data : {},
            verb: action && action.verb ? action.verb : undefined
        });
    };
}

ใช้ Power Fx เพื่อทำให้การ์ดของคุณปรับเปลี่ยนตาม

คุณสามารถใช้สูตร Power Fx เพื่อรวมข้อมูลแบบไดนามิกบนการ์ดของคุณโดยอ้างอิงตัวแปรจากหัวข้อหรือเอเจนต์ของคุณ

  1. เลือกจุดสามจุด (...) ของโหนด แล้วเลือก คุณสมบัติ

  2. ในแผงคุณสมบัติของโหนดอะแดปทีฟการ์ด ให้สลับไปยังสูตร การเลือก สูตร จะแปลงการแสดง JSON ของการ์ดของคุณเป็นสูตร Power Fx โดยอัตโนมัติ

    ภาพหน้าจอของตัวเลือกในการสลับไปเป็นสูตร Power Fx แทน JSON บนแผงคุณสมบัติโหนดของการ์ดที่ปรับเปลี่ยนได้

    ตัวอย่างเช่น เริ่มต้นด้วยตัวอักษร JSON ต่อไปนี้สำหรับการ์ด:

    {
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [{
      "type": "ColumnSet",
      "columns": [{
          "type": "Column",
          "width": 2,
          "items": [{
              "type": "TextBlock",
              "text": "Tell us about yourself",
              "weight": "Bolder",
              "size": "Medium",
              "wrap": true,
              "style": "heading"
            }, {
              "type": "TextBlock",
              "text": "We just need a few more details to get you booked for the trip of a lifetime!",
              "isSubtle": true,
              "wrap": true
            }, {
              "type": "Input.Text",
              "id": "myName",
              "label": "Your name (Last, First)",
              "isRequired": true,
              "regex": "^[A-Z][a-z]+, [A-Z][a-z]+$",
              "errorMessage": "Please enter your name in the specified format"
            }
          ]
        }
      ]
    }
  ],
  "actions": [{
      "type": "Action.Submit",
      "title": "Submit"
    }
  ]
}

    นี่คือสูตรผลลัพธ์ของ Power Fx ที่ใช้ตัวแปรสองรายการ Topic.Title และ Topic.Subtitle แทนข้อความที่ฮาร์ดโค้ดจากสัญพจน์ JSON (ตัวอย่างนี้ถือว่าตัวแปรมีการกำหนดไว้ในหัวข้อของคุณ)

    {
  '$schema': "http://adaptivecards.io/schemas/adaptive-card.json",
  type: "AdaptiveCard",
  version: "1.5",
  body: [
    {
      type: "ColumnSet",
      columns: [
        {
          type: "Column",
          width: "2",
          items: [
            {
              type: "TextBlock",
              text: Topic.Title,
              weight: "Bolder",
              size: "Medium",
              wrap: true,
              style: "heading"
            },
            {
              type: "TextBlock",
              text: Topic.Subtitle,
              isSubtle: true,
              wrap: true
            },
            {
              type: "Input.Text",
              id: "myName",
              label: "Your name (Last, First)",
              isRequired: true,
              regex: "^[A-Z][a-z]+, [A-Z][a-z]+$",
              errorMessage: "Please enter your name in the specified format"
            }
          ]
        }
      ]
    }
  ],
  actions: [
    {
      type: "Action.Submit",
      title: "Submit"
    }
  ]
}

สำคัญ

เมื่อคุณเริ่มแก้ไขในแผงสูตร คุณไม่สามารถกลับไปใช้โค้ด JSON เดิมได้ หากต้องการอนุญาตให้มีการออกแบบและการเปลี่ยนแปลงซ้ํา ให้บันทึกสําเนาของ JSON ต้นฉบับในบันทึกย่อของคุณเองหรือเป็นข้อคิดเห็นในโหนด ข้อควรระวังนี้ช่วยให้คุณสามารถย้อนกลับการเปลี่ยนแปลงได้ถ้าจําเป็น

  • Last updated on