Robot létrehozása a Bot Connector szolgáltatással a Bot Connector API-val

Cikk
10/07/2023

A Bot Connector szolgáltatás lehetővé teszi, hogy a robot az Azure Portal konfigurált csatornákkal váltson üzeneteket az iparági szabványnak megfelelő REST és JSON használatával HTTPS-en keresztül. Ez az oktatóanyag végigvezeti a Bot Framework hozzáférési jogkivonatának beszerzésén, valamint a Bot Connector szolgáltatás használatával az üzenetek felhasználóval való cseréjének folyamatán.

Hozzáférési jogkivonat lekérése

Fontos

Ha még nem tette meg, regisztrálnia kell a robotot a Bot Frameworkben az alkalmazásazonosító és a jelszó beszerzéséhez. Hozzáférési jogkivonat beszerzéséhez szüksége lesz a robot AppID azonosítójára és jelszavára.

A Bot Connector szolgáltatással való kommunikációhoz meg kell adnia egy hozzáférési jogkivonatot az Authorization egyes API-kérések fejlécében az alábbi formátumban:

Authorization: Bearer ACCESS_TOKEN

A robot hozzáférési jogkivonatát egy API-kérés kiadásával szerezheti be.

Kérés

Ha olyan hozzáférési jogkivonatot szeretne kérni, amely a Bot Connector szolgáltatás felé irányuló kérések hitelesítésére használható, adja ki a következő kérést, és cserélje le a MICROSOFT-APP-ID és a MICROSOFT-APP-PASSWORD elemet a robot Bot Frameworkben való regisztrálásakor kapott alkalmazásazonosítóra és jelszóra.

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

Reagálás

Ha a kérés sikeres, egy HTTP 200-választ kap, amely megadja a hozzáférési jogkivonatot és a lejárattal kapcsolatos információkat.

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

Tipp

A Bot Connector szolgáltatásban történő hitelesítésről további információt a Hitelesítés című témakörben talál.

Exchange-üzenetek a felhasználóval

A beszélgetés a felhasználó és a robot között váltott üzenetek sorozata.

Üzenet fogadása a felhasználótól

Amikor a felhasználó üzenetet küld, a Bot Framework Connector POST-kérést küld a robot regisztrálásakor megadott végpontnak. A kérelem törzse egy Tevékenység objektum. Az alábbi példa azt a kéréstörzset mutatja be, amelyet a robot akkor kap, amikor a felhasználó egyszerű üzenetet küld a robotnak.

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

Válasz a felhasználó üzenetére

Ha a robot végpontja olyan kérést POST kap, amely a felhasználótól érkező üzenetet (például üzenetet) jelöl, type = használja a kérelemben szereplő információkat a válasz tevékenységobjektumának létrehozásához.

Állítsa a beszélgetés tulajdonságot a felhasználó üzenetében található beszélgetési tulajdonság tartalmára.
Állítsa a from tulajdonságot a címzett tulajdonság tartalmára a felhasználó üzenetében.
Állítsa a címzett tulajdonságot a feladó tulajdonság tartalmának a felhasználó üzenetében.
Állítsa be a szöveg és a mellékletek tulajdonságait a megfelelő módon.

serviceUrl A bejövő kérelem tulajdonságával azonosíthatja azt az alap URI-t, amelyet a robotnak használnia kell a válasz kiadásához.

A válasz POST elküldéséhez az Activity objektumnak a következő címre kell /v3/conversations/{conversationId}/activities/{activityId}küldenie az objektumot az alábbi példában látható módon. A kérés törzse egy Activity objektum, amely arra kéri a felhasználót, hogy válasszon ki egy rendelkezésre álló időpontot. Az alap URI beállításával kapcsolatos részletekért lásd: API-referencia.

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

Ebben a példakérésben https://smba.trafficmanager.net/teams az alap URI-t jelöli, a robottal kapcsolatos problémákat okozó kérések alap URI-ja pedig eltérő lehet. Az alap URI beállításával kapcsolatos részletekért lásd: API-referencia.

Fontos

Ahogy az ebben a példában is látható, az Authorization egyes elküldött API-kérések fejlécének tartalmaznia kell a Bearer szót, majd a Bot Frameworkből beszerzett hozzáférési jogkivonatot.

Ha egy másik üzenetet szeretne küldeni, amely lehetővé teszi a felhasználó számára, hogy egy gombra kattintva válasszon ki egy időpontot, POST egy másik kérést ugyanarra a végpontra:

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

Következő lépések

Ebben az oktatóanyagban hozzáférési jogkivonatot szerzett be a Bot Frameworkből, és a Bot Connector szolgáltatással váltott üzeneteket a felhasználóval. A robot teszteléséhez és hibakereséséhez használhatja a Bot Framework Emulator. Ha meg szeretné osztani a robotot másokkal, konfigurálnia kell, hogy egy vagy több csatornán fusson.