Bot BağlayıcıSı API'siyle Bot Bağlayıcısı hizmetiyle bot oluşturma

Makale
10/07/2023

Bot Bağlayıcısı hizmeti, endüstri standardı REST ve JSON kullanarak HTTPS üzerinden botunuzun Azure portal yapılandırılmış kanallarla ileti alışverişinde bulunmasını sağlar. Bu öğretici, Bot Framework'ten erişim belirteci alma ve kullanıcıyla ileti alışverişi yapmak için Bot Bağlayıcısı hizmetini kullanma işleminde size yol gösterir.

Bir erişim belirteci alma

Önemli

Henüz yapmadıysanız, Uygulama Kimliğini ve parolasını almak için botunuzu Bot Framework'e kaydetmeniz gerekir. Erişim belirteci almak için botu AppID ve parolası gerekir.

Bot Bağlayıcısı hizmetiyle iletişim kurmak için, her API isteğinin Authorization üst bilgisinde şu biçimi kullanarak bir erişim belirteci belirtmeniz gerekir:

Authorization: Bearer ACCESS_TOKEN

Bir API isteği vererek botunuz için erişim belirtecini alabilirsiniz.

İstek

Bot Bağlayıcısı hizmetinde isteklerin kimliğini doğrulamak için kullanılabilecek bir erişim belirteci istemek için aşağıdaki isteği gönderin. Microsoft-APP-ID ve MICROSOFT-APP-PASSWORD değerlerini Bot Framework'e kaydettiğinizde elde ettiğiniz Uygulama Kimliği ve parola ile değiştirin.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

Yanıt

İstek başarılı olursa erişim belirtecini ve süre sonu bilgilerini belirten bir HTTP 200 yanıtı alırsınız.

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

İpucu

Bot Bağlayıcısı hizmetinde kimlik doğrulaması hakkında daha fazla bilgi için bkz. Kimlik doğrulaması.

Kullanıcıyla ileti alışverişi

Konuşma, kullanıcıyla botunuz arasında ileti alışverişi yapılan bir dizi iletidir.

Kullanıcıdan ileti alma

Kullanıcı bir ileti gönderdiğinde, Bot Framework Bağlayıcısı botunuzu kaydettiğinizde belirttiğiniz uç noktaya bir istek gönderir. İsteğin gövdesi bir Activity nesnesidir. Aşağıdaki örnek, kullanıcı bota basit bir ileti gönderdiğinde bota gönderilen istek gövdesini gösterir.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

Kullanıcının iletisini yanıtlama

Botunuzun uç noktası kullanıcıdan bir iletiyi (örneğin, ileti) temsil eden bir POST istek aldığında, type = yanıtınız için Activity nesnesini oluşturmak üzere bu istekteki bilgileri kullanın.

Konuşma özelliğini kullanıcının iletisindeki konuşma özelliğinin içeriğine ayarlayın.
from özelliğini, kullanıcının iletisindeki alıcı özelliğinin içeriğine ayarlayın.
Alıcının özelliğini, kullanıcının iletisindeki from özelliğinin içeriğine ayarlayın.
Metin ve ekler özelliklerini uygun şekilde ayarlayın.

serviceUrl Botunuzun yanıtını vermek için kullanması gereken temel URI'yi belirlemek için gelen istekteki özelliğini kullanın.

Yanıtı göndermek için nesnenizi POSTActivity/v3/conversations/{conversationId}/activities/{activityId}aşağıdaki örnekte gösterildiği gibi öğesine gönderin. Bu isteğin gövdesi, kullanıcıdan uygun bir Activity randevu saati seçmesini isteyen bir nesnedir. Temel URI'yi ayarlama hakkında ayrıntılı bilgi için bkz. API Başvurusu.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de... 
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have these times available:",
    "replyToId": "bf3cc9a2f5de..."
}

Bu örnek istekte temel https://smba.trafficmanager.net/teams URI'yi temsil eder; bot sorunlarınızın farklı olabileceği isteklerin temel URI'sini temsil eder. Temel URI'yi ayarlama hakkında ayrıntılı bilgi için bkz. API Başvurusu.

Önemli

Bu örnekte gösterildiği gibi, Authorization gönderdiğiniz her API isteğinin üst bilgisi Taşıyıcı sözcüğünü ve ardından Bot Framework'ten aldığınız erişim belirtecini içermelidir.

Kullanıcının bir düğmeye POST ve aynı uç noktaya yönelik başka bir isteğe tıklayarak uygun bir randevu saatini seçmesine olanak tanıyan başka bir ileti göndermek için:

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de... 
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "attachmentLayout": "list",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.card.thumbnail",
        "content": {
          "buttons": [
            {
              "type": "imBack",
              "title": "10:30",
              "value": "10:30"
            },
            {
              "type": "imBack",
              "title": "11:30",
              "value": "11:30"
            },
            {
              "type": "openUrl",
              "title": "See more",
              "value": "http://www.contososalon.com/scheduling"
            }
          ]
        }
      }
    ],
    "replyToId": "bf3cc9a2f5de..."
}

Sonraki adımlar

Bu öğreticide, Bot Framework'ten bir erişim belirteci edindiyseniz ve kullanıcıyla ileti alışverişi yapmak için Bot Bağlayıcısı hizmetini kullandınız. Botunuzu test etmek ve hatalarını ayıklamak için Bot Framework Emulator kullanabilirsiniz. Botunuzu başkalarıyla paylaşmak isterseniz botunuzu bir veya daha fazla kanalda çalışacak şekilde yapılandırmanız gerekir.