Bagikan melalui

Menulis manifes keterampilan

  • Artikel

BERLAKU UNTUK: SDK v4

Manifes keterampilan adalah file JSON yang menjelaskan tindakan yang dapat diambil keterampilan, parameter input dan outputnya, dan titik akhir keterampilan. Manifes berisi informasi yang dapat dibaca mesin yang dapat digunakan pengembang untuk mengakses keterampilan dari bot lain.

Artikel ini menjelaskan versi skema manifes keterampilan Bot Framework yang didukung.

Versi Catatan
versi 2.2 Memperbarui beberapa properti URI untuk menerima referensi URI.
versi 2.1 Menambahkan kemampuan untuk menjelaskan aktivitas proaktif yang dapat dikirim keterampilan dan model pengiriman yang digunakan keterampilan.
versi 2.0 Versi awal.

Skema manifes keterampilan Bot Framework menggunakan draf 7 kosakata skema JSON.

Prasyarat

Manifes keterampilan

Manifes keterampilan berisi berbagai kategori informasi:

  • Metadata yang menjelaskan keterampilan pada tingkat umum.
  • Daftar titik akhir yang disediakan keterampilan.
  • Daftar opsional aktivitas yang dapat diterima keterampilan dan dikirim secara proaktif.
  • Objek definisi opsional yang berisi skema untuk objek yang dirujuk oleh bagian lain dari dokumen.
  • Daftar opsional model pengiriman yang didukung keterampilan.

Tabel berikut menjelaskan skema lengkap untuk v2.2 dari manifes keterampilan Bot Framework.

Kategori/Bidang Jenis/Format Wajib Deskripsi
Metadata
$id String Wajib Pengidentifikasi untuk manifes keterampilan.
$schema String/URI Wajib URI HTTPS dari sumber daya skema JSON yang menjelaskan format manifes. Untuk versi 2.2, URI adalah https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
Hak cipta String Opsional Pemberitahuan hak cipta untuk keterampilan.
description String Opsional Deskripsi keterampilan yang dapat dibaca manusia.
iconUrl String/referensi URI Opsional URI ikon yang ditampilkan untuk keterampilan.
lisensi String Opsional Perjanjian lisensi untuk keterampilan.
nama String Wajib Nama keterampilan.
privacyUrl String/referensi URI Opsional URI deskripsi privasi untuk keterampilan.
publisherName String Wajib Nama penerbit keterampilan.
tag Array string Opsional Sekumpulan tag untuk keterampilan. Jika ada, setiap tag harus unik.
versi String Wajib Versi keterampilan yang dijelaskan manifes.
Titik Akhir
Titik akhir array titik akhir Wajib Daftar titik akhir yang didukung oleh keterampilan. Setidaknya satu titik akhir harus ditentukan. Setiap titik akhir harus unik.
Kegiatan
aktivitas Objek yang berisi objek aktivitas bernama Opsional Kumpulan aktivitas awal yang diterima oleh keterampilan.
aktivitasSent Objek yang berisi objek aktivitas bernama Opsional Menjelaskan aktivitas proaktif yang dapat dikirim keterampilan.
Definisi
definisi Objek Opsional Objek yang berisi subskema untuk objek yang digunakan dalam manifes.
Mengirimkan model
dispatchModels objek dispatchModels Opsional Menjelaskan model bahasa dan niat tingkat atas yang didukung oleh keterampilan. Lihat Mengirimkan model untuk skema untuk objek ini.

Titik akhir

Setiap objek titik akhir menjelaskan titik akhir yang didukung oleh keterampilan.

Contoh ini mencantumkan dua titik akhir untuk keterampilan.

"endpoints": [
    {
        "name": "americas",
        "protocol": "BotFrameworkV3",
        "description": "Production endpoint for SkillBot in the Americas",
        "endpointUrl": "http://myskill.contoso.com/api/messages",
        "msAppId": "00000000-0000-0000-0000-000000000000"
    },
    {
        "name": "eu",
        "protocol": "BotFrameworkV3",
        "description": "Production endpoint for SkillBot in Europe",
        "endpointUrl": "http://myskill.contoso.com/api/messages",
        "msAppId": "11111111-0000-0000-0000-000000000000"
    }
],

objek titik akhir

Menjelaskan titik akhir yang didukung oleh keterampilan.

Bidang Jenis/Format Wajib Deskripsi
description String Opsional Deskripsi titik akhir.
endpointUrl String/URI Wajib Titik akhir URI untuk keterampilan.
msAppId String Wajib Microsoft AppId (GUID) untuk keterampilan, digunakan untuk mengautentikasi permintaan. Harus cocok dengan ekspresi reguler: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$.
nama String Wajib Nama unik untuk titik akhir.
protokol String Opsional Protokol Bot yang didukung. Defaultnya adalah "BotFrameworkV3", yang mewakili Bot Koneksi or API versi 3. Gunakan nilai default kecuali keterampilan Anda secara khusus menggunakan protokol yang berbeda.

Aktivitas

Setiap objek aktivitas menjelaskan aktivitas yang diterima oleh keterampilan. Keterampilan memulai tindakan atau tugas berdasarkan aktivitas awal yang diterimanya. Nama yang terkait dengan objek aktivitas menunjukkan tindakan atau tugas yang akan dilakukan keterampilan.

Beberapa jenis aktivitas memiliki properti nilai yang dapat digunakan untuk memberikan input tambahan ke keterampilan. Ketika keterampilan berakhir (menyelesaikan tindakan), keterampilan dapat memberikan nilai pengembalian di properti nilai aktivitas akhir percakapan terkait.

Jenis aktivitas yang diizinkan adalah: pesan, peristiwa, pemanggilan, dan aktivitas lainnya . Keterampilan dapat menerima aktivitas pemanggilan, tetapi tidak dapat mengirimnya.

Berikut adalah deskripsi aktivitas sampel.

"bookFlight": {
    "description": "Books a flight",
    "type": "event",
    "name": "BookFlight",
    "value": {
        "$ref": "#/definitions/bookingInfo"
    },
    "resultValue": {
        "$ref": "#/definitions/bookingInfo"
    }
},

objek eventActivity

Menjelaskan aktivitas peristiwa yang diterima atau dikirim oleh keterampilan. Arti aktivitas peristiwa didefinisikan oleh bidang namanya, yang bermakna dalam cakupan keterampilan.

Bidang Jenis Wajib Deskripsi
description String Opsional Deskripsi tindakan yang harus dimulai oleh peristiwa.
nama String Wajib Nilai properti nama aktivitas peristiwa.
resultValue Objek Opsional Definisi skema JSON dari jenis objek yang dapat dikembalikan oleh tindakan.
jenis String Wajib Jenis aktivitas. Harus "peristiwa".
value Objek Opsional Definisi skema JSON dari jenis objek yang diharapkan tindakan ini sebagai input.

objek invokeActivity

Menjelaskan aktivitas pemanggilan yang diterima oleh keterampilan. Arti aktivitas pemanggilan didefinisikan oleh bidang namanya, yang bermakna dalam cakupan keterampilan.

Bidang Jenis Wajib Deskripsi
description String Opsional Deskripsi tindakan yang harus dimulai oleh pemanggilan.
nama String Wajib Nilai properti nama aktivitas pemanggilan.
resultValue Objek Opsional Definisi skema JSON dari jenis objek yang dapat dikembalikan oleh tindakan terkait.
jenis String Wajib Jenis aktivitas. Harus "dipanggil".
value Objek Opsional Definisi skema JSON dari jenis objek yang diharapkan tindakan ini sebagai input.

objek messageActivity

Menjelaskan aktivitas pesan yang diterima atau dikirim oleh keterampilan. Properti teks aktivitas pesan berisi ucapan pengguna atau bot.

Bidang Jenis Wajib Deskripsi
description String Opsional Deskripsi tindakan.
resultValue Objek Opsional Definisi skema JSON dari jenis objek yang dapat dikembalikan oleh tindakan terkait.
jenis String Wajib Jenis aktivitas. Harus "pesan".
value Objek Opsional Definisi skema JSON dari jenis objek yang diharapkan tindakan ini sebagai input.

Objek Aktivitas lainnya

Menjelaskan jenis aktivitas lain yang diterima atau dikirim oleh keterampilan.

Bidang Jenis Wajib Deskripsi
jenis String Wajib Jenis aktivitas. Harus salah satu jenis aktivitas Bot Framework lainnya: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace", atau "typing".

Objek Aktivitas lainnya dapat mencakup properti lain, tetapi skema manifes keterampilan tidak menentukan maknanya.

Definisi

Setiap definisi menjelaskan subskema yang dapat dikonsumsi oleh bagian lain dari dokumen.

Berikut adalah subskema sampel untuk informasi pemesanan penerbangan.

"bookingInfo": {
    "type": "object",
    "required": [
        "origin"
    ],
    "properties": {
        "origin": {
            "type": "string",
            "description": "this is the origin city for the flight"
        },
        "destination": {
            "type": "string",
            "description": "this is the destination city for the flight"
        },
        "date": {
            "type": "string",
            "description": "The date for the flight in YYYY-MM-DD format"
        }
    }
},

Mengirimkan model

Model pengiriman berisi daftar model bahasa dan daftar niat tingkat atas yang didukung oleh keterampilan. Ini adalah fitur canggih untuk memungkinkan pengembang konsumen keterampilan membuat model bahasa yang menggabungkan fitur bot konsumen dan keterampilan.

Setiap model bahasa menggunakan .lu format file atau .qna . Untuk informasi selengkapnya tentang format ini, lihat format file .lu dan format file .qna.

Nama lokal adalah kombinasi dari kode budaya huruf kecil dua huruf ISO 639 yang terkait dengan bahasa dan kode subkultur huruf besar dua huruf ISO 3166 opsional yang terkait dengan negara atau wilayah, misalnya "en" atau "en-US".

Bidang Jenis Wajib Deskripsi
niat Array string Opsional Daftar niat tingkat atas yang didukung oleh keterampilan. Setiap niat harus unik.
bahasa Objek yang berisi array languageModel bernama Opsional Daftar model bahasa yang didukung oleh keterampilan. Setiap nama adalah lokal untuk model bahasa, dan array berisi model bahasa untuk lokal tersebut. Model pengiriman harus mendukung setidaknya satu lokal. Setiap lokal dalam bidang bahasa harus unik.

Berikut adalah contoh model pengiriman yang berisi dua model bahasa di tiga lokal. Ini juga menjelaskan dua niat tingkat atas yang dapat dikenali keterampilan.

"dispatchModels": {
    "languages": {
        "en": [
            {
                "name": "SkillBot LU (English)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-en.lu",
                "description": "English language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (English)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-en.qna",
                "description": "English language model for the skill (QnAMaker)"
            }
        ],
        "es-ES": [
            {
                "name": "SkillBot LU (Spanish-Spain)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-es-ES.lu",
                "description": "Spanish (Spain) language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (Spanish-Spain)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-es-ES.qna",
                "description": "Spanish (Spain) language model for the skill (QnAMaker)"
            }
        ],
        "es-MX": [
            {
                "name": "SkillBot LU (Spanish-Mexico)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-es-MX.lu",
                "description": "Spanish (Mexico) language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (Spanish-Mexico)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-es-MX.qna",
                "description": "Spanish (Mexico) language model for the skill (QnAMaker)"
            }
        ]
    },
    "intents": [
        "bookFlight",
        "getWeather"
    ]
},

objek languageModel

Menjelaskan model bahasa untuk budaya tertentu. Namanya adalah nama lokal.

Bidang Jenis/Format Wajib Deskripsi
contentType String Wajib Jenis model bahasa.
description String Opsional Deskripsi model bahasa.
nama String Wajib Nama model bahasa.
url String/referensi URI Wajib URL untuk model bahasa.

Manifes sampel

Berikut adalah sampel lengkap manifes v2.2 untuk keterampilan yang mengekspos beberapa aktivitas.

{
    "$schema": "https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json",
    "$id": "SkillBot",
    "name": "Sample skill definition that can handle multiple types of activities",
    "version": "1.0",
    "description": "This is a sample skill definition for multiple activity types",
    "publisherName": "Microsoft",
    "privacyUrl": "https://myskill.contoso.com/privacy.html",
    "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
    "license": "",
    "iconUrl": "skillIcon.png",
    "tags": [
        "sample",
        "travel",
        "weather"
    ],
    "endpoints": [
        {
            "name": "americas",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for SkillBot in the Americas",
            "endpointUrl": "http://myskill.contoso.com/api/messages",
            "msAppId": "00000000-0000-0000-0000-000000000000"
        },
        {
            "name": "eu",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for SkillBot in Europe",
            "endpointUrl": "http://myskill.contoso.com/api/messages",
            "msAppId": "11111111-0000-0000-0000-000000000000"
        }
    ],
    "dispatchModels": {
        "languages": {
            "en": [
                {
                    "name": "SkillBot LU (English)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-en.lu",
                    "description": "English language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (English)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-en.qna",
                    "description": "English language model for the skill (QnAMaker)"
                }
            ],
            "es-ES": [
                {
                    "name": "SkillBot LU (Spanish-Spain)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-es-ES.lu",
                    "description": "Spanish (Spain) language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (Spanish-Spain)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-es-ES.qna",
                    "description": "Spanish (Spain) language model for the skill (QnAMaker)"
                }
            ],
            "es-MX": [
                {
                    "name": "SkillBot LU (Spanish-Mexico)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-es-MX.lu",
                    "description": "Spanish (Mexico) language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (Spanish-Mexico)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-es-MX.qna",
                    "description": "Spanish (Mexico) language model for the skill (QnAMaker)"
                }
            ]
        },
        "intents": [
            "bookFlight",
            "getWeather"
        ]
    },
    "activities": {
        "bookFlight": {
            "description": "Books a flight",
            "type": "event",
            "name": "BookFlight",
            "value": {
                "$ref": "#/definitions/bookingInfo"
            },
            "resultValue": {
                "$ref": "#/definitions/bookingInfo"
            }
        },
        "getWeather": {
            "description": "Retrieves and returns the weather for the user's location",
            "type": "invoke",
            "name": "GetWeather",
            "value": {
                "$ref": "#/definitions/location"
            },
            "resultValue": {
                "$ref": "#/definitions/weatherReport"
            }
        },
        "message": {
            "type": "message",
            "description": "Receives the user's' utterance and attempts to resolve it using the skill's LU models"
        },
        "typing": {
            "type": "typing"
        },
        "conversationUpdate": {
            "type": "conversationUpdate"
        }
    },
    "definitions": {
        "localeValue": {
            "type": "object",
            "properties": {
                "locale": {
                    "type": "string",
                    "description": "The current user's locale ISO code"
                }
            }
        },
        "bookingInfo": {
            "type": "object",
            "required": [
                "origin"
            ],
            "properties": {
                "origin": {
                    "type": "string",
                    "description": "this is the origin city for the flight"
                },
                "destination": {
                    "type": "string",
                    "description": "this is the destination city for the flight"
                },
                "date": {
                    "type": "string",
                    "description": "The date for the flight in YYYY-MM-DD format"
                }
            }
        },
        "weatherReport": {
            "type": "array",
            "description": "Array of forecasts for the next week.",
            "items": [
                {
                    "type": "string"
                }
            ]
        },
        "location": {
            "type": "object",
            "description": "Location metadata",
            "properties": {
                "latitude": {
                    "type": "number",
                    "title": "Latitude"
                },
                "longitude": {
                    "type": "number",
                    "title": "Longitude"
                },
                "postalCode": {
                    "type": "string",
                    "title": "Postal code"
                }
            }
        }
    },
    "activitiesSent": {
        "flightUpdated": {
            "type": "event",
            "name": "FlightUpdated",
            "description": "Event which is sent by the skill when there is an update in flight info",
            "value": {
                "type": "object",
                "description": "Flight update information",
                "properties": {
                    "flightNumber": {
                        "type": "string"
                    },
                    "departureDate": {
                        "type": "string",
                        "description": "The departure date for the flight in YYYY-MM-DD format"
                    },
                    "departureTime": {
                        "type": "string",
                        "description": "The departure time for the flight in HH-MM format"
                    }
                }
            }
        }
    }
}

Langkah berikutnya