Beceri bildirimi yazma

  • Makale

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Beceri bildirimi, bir becerinin gerçekleştirebileceği eylemleri, giriş ve çıkış parametrelerini ve becerinin uç noktalarını açıklayan bir JSON dosyasıdır. Bildirim, bir geliştiricinin başka bir bottan beceriye erişmek için kullanabileceği makine tarafından okunabilir bilgiler içerir.

Bu makalede Bot Framework beceri bildirim şemasının desteklenen sürümleri açıklanmaktadır.

Sürüm Notlar
sürüm 2.2 Bazı URI özellikleri URI başvurularını kabul etmek için güncelleştirildi.
sürüm 2.1 Becerinin gönderebileceği proaktif etkinlikleri ve becerinin kullandığı gönderim modellerini açıklama yeteneği ekler.
sürüm 2.0 İlk sürüm.

Bot Framework beceri bildirimi şemaları, JSON şema sözlüğü taslak 7'yi kullanır.

Ön koşullar

Beceri bildirimi

Beceri bildirimi farklı bilgi kategorileri içerir:

  • Beceriyi genel düzeyde açıklayan meta veriler.
  • Becerinin sağladığı uç noktaların listesi.
  • Becerinin alabileceği ve proaktif olarak gönderebileceği etkinliklerin isteğe bağlı listeleri.
  • Belgenin diğer bölümleri tarafından başvuruda bulunan nesneler için şemalar içeren isteğe bağlı bir tanımlar nesnesi.
  • Becerinin desteklediği dağıtım modellerinin isteğe bağlı bir listesi.

Aşağıdaki tabloda, Bot Framework beceri bildiriminin v2.2 için tam şeması açıklanmaktadır.

Kategori/Alan Tür/Biçim Zorunlu Tanım
Meta veriler
$id String Zorunlu Beceri bildiriminin tanımlayıcısı.
$schema Dize/URI Zorunlu Bildirimin biçimini açıklayan bir JSON şema kaynağının HTTPS URI'sini. Sürüm 2.2 için URI'dir https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
telif hakkı String İsteğe bağlı Beceri için telif hakkı bildirimi.
açıklama String İsteğe bağlı Becerinin insan tarafından okunabilen bir açıklaması.
iconUrl Dize/URI başvurusu İsteğe bağlı Beceri için gösterilecek simgenin URI'si.
lisans String İsteğe bağlı Beceri için lisans sözleşmesi.
name String Zorunlu Becerinin adı.
privacyUrl Dize/URI başvurusu İsteğe bağlı Beceri için gizlilik açıklamasının URI'sini.
publisherName String Zorunlu Beceri yayımcısının adı.
etiketler Dize dizisi İsteğe bağlı Beceri için bir dizi etiket. Varsa, her etiket benzersiz olmalıdır.
sürüm String Zorunlu Bildirimin tanımladığı becerinin sürümü.
Uç Noktalar
uç noktalar uç nokta dizisi Zorunlu Beceri tarafından desteklenen uç noktaların listesi. En az bir uç nokta tanımlanmalıdır. Her uç nokta benzersiz olmalıdır.
Etkinlikler
etkinlikler Adlandırılmış etkinlik nesnelerini içeren nesne İsteğe bağlı Beceri tarafından kabul edilen ilk etkinlikler kümesi.
etkinliklerSent Adlandırılmış etkinlik nesnelerini içeren nesne İsteğe bağlı Becerinin gönderebileceği proaktif etkinlikleri açıklar.
Tanımlar
Tanım Nesne İsteğe bağlı Bildirimde kullanılan nesneler için altchemas içeren bir nesne.
Dağıtım modelleri
dispatchModels dispatchModels nesnesi İsteğe bağlı Beceri tarafından desteklenen dil modellerini ve üst düzey amaçları açıklar. Bu nesnenin şeması için bkz . Dağıtım modelleri .

Uç Noktalar

Her uç nokta nesnesi, beceri tarafından desteklenen bir uç noktayı açıklar.

Bu örnekte bir beceri için iki uç nokta listelenir.

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

uç nokta nesnesi

Beceri tarafından desteklenen bir uç noktayı açıklar.

Alan Tür/Biçim Zorunlu Tanım
açıklama String İsteğe bağlı Uç noktanın açıklaması.
endpointUrl Dize/URI Zorunlu Beceri için URI uç noktası.
msAppId String Zorunlu İsteklerin kimliğini doğrulamak için kullanılan beceri için Microsoft AppId (GUID). Normal ifadeyle eşleşmelidir: ^[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}$.
name String Zorunlu Uç noktanın benzersiz adı.
Protokolü String İsteğe bağlı Desteklenen Bot protokolü. Varsayılan değer, Bot Bağlan or API sürüm 3'lerini temsil eden "BotFrameworkV3"dür. Beceriniz özel olarak farklı bir protokol kullanmıyorsa varsayılan değeri kullanın.

Aktiviteler

Her etkinlik nesnesi, beceri tarafından kabul edilen bir etkinliği açıklar. Beceri, aldığı ilk etkinliğe göre bir eylem veya görev başlatır. Etkinlik nesnesiyle ilişkili ad, becerinin gerçekleştireceği eylemi veya görevi gösterir.

Bazı etkinlik türleri, beceriye ek giriş sağlamak için kullanılabilecek bir değer özelliğine sahiptir. Beceri sona erdiğinde (eylemi tamamladığında), ilişkili konuşma sonu etkinliğinin değer özelliğinde bir dönüş değeri sağlayabilir.

İzin verilen etkinlik türleri şunlardır: ileti, olay, çağırma ve diğer etkinlikler. Bir beceri bir çağırma etkinliği alabilir, ancak gönderemez.

Aşağıda örnek etkinlik açıklaması verilmiştir.

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

eventActivity nesnesi

Beceri tarafından kabul edilen veya gönderilen bir olay etkinliğini açıklar. Olay etkinliğinin anlamı, beceri kapsamında anlamlı olan ad alanıyla tanımlanır.

Alan Tür Zorunlu Tanım
açıklama String İsteğe bağlı Olayın başlatması gereken eylemin açıklaması.
name String Zorunlu Olay etkinliğinin ad özelliğinin değeri.
resultValue Nesne İsteğe bağlı Eylemin döndürebileceği nesne türünün JSON şema tanımı.
tür String Zorunlu Etkinlik türü. "Olay" olmalıdır.
value Nesne İsteğe bağlı Bu eylemin giriş olarak beklediği nesne türünün JSON şema tanımı.

invokeActivity nesnesi

Beceri tarafından kabul edilen bir çağırma etkinliğini açıklar. Çağırma etkinliğinin anlamı, beceri kapsamında anlamlı olan ad alanıyla tanımlanır.

Alan Tür Zorunlu Tanım
açıklama String İsteğe bağlı Çağırmanın başlatması gereken eylemin açıklaması.
name String Zorunlu Çağırma etkinliğinin ad özelliğinin değeri.
resultValue Nesne İsteğe bağlı İlişkili eylemin döndürebileceği nesne türünün JSON şema tanımı.
tür String Zorunlu Etkinlik türü. "Invoke" olmalıdır.
value Nesne İsteğe bağlı Bu eylemin giriş olarak beklediği nesne türünün JSON şema tanımı.

messageActivity nesnesi

Beceri tarafından kabul edilen veya gönderilen bir ileti etkinliğini açıklar. İleti etkinliğinin metin özelliği kullanıcının veya botunun konuşmasını içerir.

Alan Tür Zorunlu Tanım
açıklama String İsteğe bağlı Eylemin açıklaması.
resultValue Nesne İsteğe bağlı İlişkili eylemin döndürebileceği nesne türünün JSON şema tanımı.
tür String Zorunlu Etkinlik türü. "İleti" olmalıdır.
value Nesne İsteğe bağlı Bu eylemin giriş olarak beklediği nesne türünün JSON şema tanımı.

otherActivities nesnesi

Beceri tarafından kabul edilen veya gönderilen diğer etkinlik türlerini açıklar.

Alan Tür Zorunlu Tanım
tür String Zorunlu Etkinlik türü. Diğer Bot Framework etkinlik türlerinden biri olmalıdır: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace", veya "typing".

OtherActivities nesnesi diğer özellikleri içerebilir, ancak beceri bildirimi şeması anlamlarını tanımlamaz.

Tanımlar

Her tanım, belgenin diğer bölümleri tarafından kullanılabilecek bir alt kimyayı açıklar.

Uçuş rezervasyon bilgileri için örnek bir alt kimya aşağıda verilmiştir.

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

Dağıtım modelleri

Gönderim modeli, dil modellerinin listesini ve beceri tarafından desteklenen en üst düzey amaçların listesini içerir. Beceri tüketicisi geliştiricisinin, tüketici ve beceri botlarının özelliklerini birleştiren bir dil modeli oluşturmasını sağlayan gelişmiş bir özelliktir.

Her dil modeli veya .qna dosya biçimini kullanır.lu. Bu biçimler hakkında daha fazla bilgi için bkz . .lu dosya biçimi ve .qna dosya biçimi.

Yerel ayar adı, bir dille ilişkilendirilmiş ISO 639 iki harfli küçük harfli kültür kodu ile bir ülke veya bölgeyle ilişkilendirilmiş isteğe bağlı ISO 3166 iki harfli büyük harfli alt kültür kodunun (örneğin, "en" veya "en-US" gibi) birleşimidir.

Alan Tür Zorunlu Tanım
Niyet Dize dizisi İsteğe bağlı Beceri tarafından desteklenen en üst düzey amaçların listesi. Her amaç benzersiz olmalıdır.
diller Adlandırılmış languageModel dizilerini içeren nesne İsteğe bağlı Beceri tarafından desteklenen dil modellerinin listesi. Her ad, dil modellerinin bulunduğu yerel ayardır ve dizi bu yerel ayarın dil modellerini içerir. Dağıtım modeli en az bir yerel ayarı desteklemelidir. Diller alanındaki her yerel ayar benzersiz olmalıdır.

Aşağıda üç yerel ayarda iki dil modeli içeren örnek bir dağıtım modeli verilmiştir. Ayrıca, becerinin tanıyabileceği iki üst düzey amacı da açıklar.

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

languageModel nesnesi

Belirli bir kültür için dil modelini açıklar. Ad bir yerel ayar adıdır.

Alan Tür/Biçim Zorunlu Tanım
Contenttype String Zorunlu Dil modelinin türü.
açıklama String İsteğe bağlı Dil modelinin açıklaması.
name String Zorunlu Dil modelinin adı.
url Dize/URI başvurusu Zorunlu Dil modelinin URL'si.

Örnek bildirim

Birden çok etkinliği kullanıma sunan bir beceriye yönelik tam örnek v2.2 bildirimi aşağıda verilmiştir.

{
    "$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"
                    }
                }
            }
        }
    }
}

Sonraki adımlar

  • Beceri uygulama.
  • Bir beceri içinde iletişim kutularını kullanma.
  • Beceri tüketicisi uygulama.
  • Beceriyi kullanmak için iletişim kutusu kullanma.