Model Tindakan Universal

2023-08-29

Konteks

Kartu Adaptif adalah cuplikan platform-agnostik UI, yang ditulis menggunakan format JSON ringan, yang dapat dibagikan oleh aplikasi dan layanan. Kartu Adaptif tidak hanya beradaptasi dengan tampilan dan nuansa host, tetapi juga memberikan kemampuan interaksi yang kaya. Untuk informasi lebih lanjut tentang Kartu Adaptif, silakan kunjungi adaptivecards.io.

Ketika Kartu Adaptif tumbuh dalam popularitas, host yang berbeda mulai mendukung model tindakan yang berbeda dan ini menyebabkan fragmentasi. Untuk mengatasi masalah ini, tim Teams, Outlook, dan Adaptive Cards bekerja membuat model tindakan Bot universal baru yang kompatibel di seluruh host. Upaya ini menyebabkan hal-hal berikut:

Generalisasi Bot dan Kerangka Kerja Bot sebagai cara untuk menerapkan skenario berbasis Kartu Adaptif untuk Teams (Bot) dan Outlook (Pesan yang Dapat Ditindaklanjuti)
Action.Executesebagai pengganti (saat ini digunakan oleh Bot) dan Action.Http (saat ini digunakan oleh Pesan yang Dapat Ditindaklanjuti Action.Submit )
Fitur populer hanya didukung oleh Pesan yang Dapat Ditindaklanjuti yang tersedia untuk Bot, yaitu:
- Kemampuan kartu untuk disegarkan pada saat kartu ditampilkan
- Kemampuan tindakan Action.Execute untuk mengembalikan kartu yang diperbarui agar segera ditampilkan di klien

Untuk informasi selengkapnya tentang Pesan yang Dapat Ditindaklanjuti di Outlook, silakan lihat dokumentasi Pesan yang Dapat Ditindaklanjuti

Untuk detail tentang berbagai skenario yang mungkin dilakukan dengan Tindakan Universal di Teams, silakan merujuk ke referensi kartu Teams.

Sebelum `Action.Execute`	Dengan `Action.Execute`

Sumber: Kartu Adaptif @ Microsoft Build 2020

Sisa dokumen ini berfokus pada dokumentasi model tindakan Bot universal dalam konteks Teams & Outlook. Jika Anda sudah menggunakan kartu Adaptif di Teams dengan Bot, Anda dapat menggunakan Bot yang sama dengan beberapa perubahan untuk mendukung Action.Execute. Jika Anda menggunakan Pesan yang Dapat Ditindaklanjuti di Outlook, Anda harus mengembangkan Bot yang mendukung Action.Execute. Saat ini dukungan pada klien Outlook untuk model tindakan Universal Bot sedang dalam pengembangan aktif.

Skema

PENTING

Model tindakan Bot universal diperkenalkan dalam skema Kartu Adaptif versi 1.4. Untuk menggunakan kemampuan baru ini, version properti Kartu Adaptif Anda harus diatur ke 1.4 atau lebih besar, seperti yang ditunjukkan pada contoh di bawah ini. Perhatikan bahwa ini akan membuat Kartu Adaptif Anda tidak kompatibel dengan klien lama (Outlook atau Teams) yang tidak mendukung model tindakan Bot universal.

Jika Anda menggunakan refresh properti dan/atau Action.Execute dan menentukan kartu versi < 1.4, hal berikut akan terjadi:

Klien Perilaku

Outlook Kartu Anda TIDAK AKAN berfungsi. refresh tidak akan dihormati dan Action.Execute tidak akan dirender. Kartu Anda bahkan dapat ditolak sepenuhnya.

Tim Kartu Anda MUNGKIN TIDAK berfungsi ( refresh mungkin tidak dihormati, dan Action.Execute tindakan mungkin tidak dirender) tergantung pada versi klien Teams.

Untuk memastikan kompatibilitas maksimum di Teams, pertimbangkan untuk menentukan tindakan Anda Action.Execute dengan Action.Submit tindakan di fallback properti .

Lihat bagian Kompatibilitas mundur di bawah ini untuk informasi selengkapnya.

Klien	Perilaku
Outlook	Kartu Anda TIDAK AKAN berfungsi. `refresh` tidak akan dihormati dan `Action.Execute` tidak akan dirender. Kartu Anda bahkan dapat ditolak sepenuhnya.
Tim	Kartu Anda MUNGKIN TIDAK berfungsi ( `refresh` mungkin tidak dihormati, dan `Action.Execute` tindakan mungkin tidak dirender) tergantung pada versi klien Teams. Untuk memastikan kompatibilitas maksimum di Teams, pertimbangkan untuk menentukan tindakan Anda `Action.Execute` dengan `Action.Submit` tindakan di `fallback` properti .

Action.Execute

Saat menulis Kartu Adaptif, gunakan Action.Execute sebagai ganti keduanya Action.Submit & Action.Http. Skema untuk Action.Execute cukup mirip dengan Action.Submit.

Contoh JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Properti

Properti	Jenis	Wajib	Deskripsi
jenis	`"Action.Execute"`	Ya	Harus berupa `"Action.Execute"` .
Verba	string	No	String kenyamanan yang dapat digunakan oleh pengembang untuk mengidentifikasi tindakan
data	`string`, `object`	No	Data awal yang memasukkan bidang akan dikombinasikan dengan. Ini pada dasarnya adalah properti 'tersembunyi'.
title	`string`	No	Label untuk tombol atau tautan yang mewakili tindakan ini.
iconUrl	`uri`	No	Ikon opsional yang akan ditampilkan pada tindakan bersama dengan judul. Mendukung URI data di Kartu Adaptif versi 1.2+
Gaya	`ActionStyle`	No	Mengontrol gaya Tindakan, yang memengaruhi bagaimana tindakan ditampilkan, diucapkan, dll.
Fallback	`<action object>`, `"drop"`	No	Menjelaskan apa yang harus dilakukan ketika Action.Execute tidak didukung oleh klien yang menampilkan kartu.
Memerlukan	`Dictionary<string>`	No	Serangkaian pasangan kunci/nilai yang menunjukkan fitur yang diperlukan item dengan versi minimum yang sesuai. Saat fitur hilang atau versi tidak mencukupi, fallback dipicu.

Mekanisme refresh

Action.ExecuteSelain itu, mekanisme refresh baru sekarang didukung, sehingga memungkinkan untuk membuat Kartu Adaptif yang secara otomatis diperbarui pada saat ditampilkan. Ini memastikan bahwa pengguna selalu melihat data terbaru. Kasus penggunaan refresh umum adalah permintaan persetujuan: setelah disetujui, sebaiknya pengguna tidak disajikan dengan kartu yang meminta mereka untuk menyetujui ketika sudah selesai, tetapi sebaliknya memberikan informasi tentang waktu permintaan disetujui dan oleh siapa.

Untuk mengizinkan Kartu Adaptif menyegarkan secara otomatis, tentukan propertinya refresh , yang menyematkan action jenis Action.Execute serta userIds array.

Properti	Jenis	Wajib	Deskripsi
action	`"Action.Execute"`	Ya	Harus merupakan instans tindakan jenis `"Action.Execute"`.
userIds	`Array<string>`	Ya	Array `MRI`pengguna yang Refresh Otomatisnya harus diaktifkan. PENTING: Jika `userIds` properti daftar tidak disertakan di bagian `refresh` kartu, kartu TIDAK akan secara otomatis di-refresh saat ditampilkan. Sebagai gantinya, tombol akan disajikan kepada pengguna untuk memungkinkan mereka menyegarkan secara manual. Alasan untuk ini adalah obrolan/saluran di Teams dapat mencakup sejumlah besar anggota; jika banyak anggota semua melihat saluran secara bersamaan, refresh otomatis tanpa syarat akan mengakibatkan banyak panggilan bersamaan ke bot, yang tidak akan menskalakan. Untuk meringankan potensi masalah skala, `userIds` properti harus selalu disertakan untuk mengidentifikasi pengguna mana yang harus mendapatkan refresh otomatis, dengan maksimum 60 ID pengguna saat ini diizinkan. Lihat userId dalam refresh untuk detail selengkapnya. Perhatikan bahwa `userIds` properti diabaikan di Outlook, dan `refresh` properti selalu secara otomatis dihormati. Tidak ada masalah skala di Outlook karena pengguna biasanya akan melihat kartu pada waktu yang berbeda.

Sampel JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "version": "1.4",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Submit",
      "verb": "personalDetailsCardRefresh"
    },
    "userIds": []
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    { 
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Catatan penting untuk pengembang Pesan yang Dapat Ditindaklaksakan Outlook

Saat mengembangkan skenario Pesan yang Dapat Ditindaklanjuti Outlook, properti Kartu originator Adaptif harus ditentukan. originator adalah Globally Unique Identified (GUID) yang dihasilkan pada saat Bot berlangganan saluran Outlook. Ini digunakan oleh Outlook untuk memvalidasi bahwa Kartu Adaptif dikirim oleh Bot resmi. Kartu Adaptif tidak akan dirender di Outlook jika originator tidak ada. originator diabaikan di Teams.

`adaptiveCard/action` Memanggil aktivitas

Action.Execute Ketika dijalankan di klien (apakah itu tindakan refresh atau tindakan yang secara eksplisit diambil oleh pengguna dengan mengklik tombol), jenis aktivitas Panggil baru - adaptiveCard/action - dibuat untuk Bot Anda. Permintaan aktivitas Pemanggilan umum adaptiveCard/action akan terlihat seperti berikut ini:

Format permintaan

{ 
  "type": "invoke",
  "name": "adaptiveCard/action",

  // ... other properties omitted for brevity

  "value": { 
    "action": { 
      "type": "Action.Execute", 
      "id": "abc", 
      "verb": "def",
      "data": { ... } 
    },
    "trigger": "automatic | manual" 
  }
}

Bidang	Deskripsi
value.action	Salinan tindakan seperti yang didefinisikan dalam Kartu Adaptif. `Action.Submit`Seperti , `data` properti tindakan mencakup nilai berbagai input dalam kartu, jika ada
value.trigger	Menunjukkan apakah tindakan dipicu secara eksplisit (oleh pengguna mengklik tombol) atau secara implisit (melalui refresh otomatis)

Format respons

Jika Bot memproses aktivitas Invoke masuk adaptiveCard/action (yaitu jika kode Bot terlibat sama sekali dalam memproses permintaan), kode status respons HTTP yang dikembalikan oleh Bot harus sama dengan 200 dan isi respons HTTP harus diformat sebagai berikut:

{ 
    "statusCode": <number (200 – 599)>, 
    "type": "<string>", 
    "value": "<object>"
}

Bidang	Deskripsi
statusCode	Kode status respons HTTP 200 TIDAK selalu berarti Bot berhasil memproses permintaan. Aplikasi klien HARUS selalu melihat `statucCode` properti dalam isi respons untuk mengetahui bagaimana Bot memproses permintaan. `statusCode` adalah angka mulai dari 200-599 yang mencerminkan nilai kode status HTTP dan dimaksudkan untuk menjadi sub-status untuk hasil bot yang memproses Pemanggilan. Nilai yang hilang, null, atau tidak ditentukan untuk `statusCode` menyiratkan 200 (Berhasil).
jenis	Sekumpulan konstanta string terkenal yang menjelaskan bentuk properti nilai yang diharapkan
value	Objek yang khusus untuk jenis isi respons

Kode status yang didukung

Tabel berikut mencantumkan nilai yang diizinkan untuk statusCode, type, dan value dalam isi respons Bot:

Kode status	Jenis	Skema Nilai	Catatan
200	`application/vnd.microsoft.card.adaptive`	`Adaptive Card`	Permintaan berhasil diproses, dan respons menyertakan Kartu Adaptif yang harus ditampilkan klien sebagai pengganti yang saat ini.
200	`application/vnd.microsoft.activity.message`	`string`	Permintaan berhasil diproses, dan respons menyertakan pesan yang harus ditampilkan klien.
400	`application/vnd.microsoft.error`	Objek Kesalahan (TODO: perlu tautan)	Permintaan masuk tidak valid.
401	`application/vnd.microsoft.activity.loginRequest`	OAuthCard (TODO: perlu tautan)	Klien perlu meminta pengguna untuk mengautentikasi.
401	`application/vnd.microsoft.error.inccorectAuthCode`	nihil	Status autentikasi yang diteruskan oleh klien salah dan autentikasi gagal.
412	`application/vnd.microsoft.error.preconditionFailed`	Objek Kesalahan (TODO: perlu tautan)	Alur autentikasi SSO gagal.
500	`application/vnd.microsoft.error`	Objek Kesalahan (TODO: perlu tautan)	Terjadi kesalahan tidak terduga.

Ringkasan: cara memanfaatkan model tindakan Bot universal

Gunakan Action.Execute alih-alih Action.Submit. Untuk memperbarui skenario yang ada di tim, ganti semua instans Action.Submit dengan Action.Execute. Untuk memutakhirkan skenario yang sudah ada di Outlook, silakan lihat bagian kompatibilitas mundur di bawah ini.
Agar kartu muncul di outlook, tambahkan originator bidang . Lihat Contoh JSON di atas.
refresh Tambahkan klausul ke Kartu Adaptif jika Anda ingin memanfaatkan mekanisme refresh otomatis atau jika skenario Anda memerlukan tampilan khusus pengguna. Pastikan untuk menentukan userIds properti untuk mengidentifikasi pengguna mana (maksimum 60) yang akan mendapatkan pembaruan otomatis.
Menangani adaptiveCard/action permintaan Panggil di Bot Anda
Setiap kali Bot Anda perlu mengembalikan kartu baru sebagai hasil dari pemrosesan Action.Execute, Anda dapat menggunakan konteks Permintaan panggilan untuk menghasilkan kartu yang dibuat secara khusus untuk pengguna tertentu. Pastikan respons sesuai dengan skema respons yang ditentukan di atas.

Kompatibilitas mundur

Outlook

Model tindakan universal baru Action.Execute adalah keberangkatan dari Action.Http model tindakan yang saat ini digunakan oleh Pesan yang Dapat Ditindaklanjuti Outlook, di mana tindakan dikodekan dalam Kartu Adaptif sebagai panggilan HTTP eksplisit. Model ini Action.Execute memungkinkan pengembang untuk menerapkan skenario yang "hanya berfungsi" di Outlook dan Teams. Skenario Pesan yang Dapat Ditindakkan dapat menggunakan Action.Http model atau model baru Action.Execute , tetapi tidak keduanya. Skenario yang menggunakan model universal Action.Execute harus diimplementasikan sebagai Bot dan berlangganan Outlook Actionable Messages saluran.

Catatan penting

Skenario yang diterapkan menggunakan model universal Action.Execute tidak akan kompatibel dengan versi Outlook yang lebih lama

Pekerjaan sedang berlangsung untuk memungkinkan skenario Pesan yang Dapat Ditindak lanjutkan yang ada untuk bermigrasi dengan mulus ke model universal Action.Execute

Tim

Agar kartu Anda kompatibel mundur dan berfungsi untuk pengguna pada versi Teams yang lebih lama, tindakan Anda Action.Execute harus menyertakan properti yang fallback didefinisikan sebagai Action.Submit. Bot Anda harus dikodekan singgahan sehingga dapat memproses dan Action.Execute Action.Submit. Perhatikan bahwa Bot Anda tidak dapat mengembalikan kartu baru saat memproses Action.Submit, sehingga perilaku fallback melalui Action.Submit akan memberikan pengalaman yang terdegradasi bagi pengguna akhir.

Catatan penting

Beberapa klien Teams yang lebih lama tidak mendukung properti fallback ketika tidak dibungkus dalam ActionSet. Agar tidak melanggar klien tersebut, sangat disarankan agar Anda membungkus semua Action.Execute di ActionSet. Lihat contoh di bawah ini tentang cara membungkus Action.Execute dalam ActionSet.

Dalam contoh di bawah ini, perhatikan version properti kartu diatur ke 1.2 dan Action.Execute didefinisikan dengan Action.Submit sebagai fallback. Ketika dirender di klien Teams yang mendukung Kartu Adaptif 1.4, Action.Execute akan dirender dan berfungsi seperti yang diharapkan. Di klien Teams yang tidak mendukung Kartu Adaptif 1.4, Action.Submit akan dirender sebagai pengganti Action.Execute.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": {
            "type": "Action.Submit",
            "title": "Submit"
          }  
        }
      ]
    }
  ]
}

Bagikan melalui