API 2.0 Botへのアップグレードガイド
アップグレードとは、現在稼働中のBotで使用しているAPIをAPI 1.0からAPI 2.0に切り替える作業を意味します。
このアップグレードにより、最適化された最新のAPIを使用したBot開発や、今後提供されるAPIの追加機能を利用することができます。
注意
2022年4月1日以降、新規登録されるBotは既定でAPI 2.0が選択されます。(API 1.0も選択可能)
BotをAPI 2.0にアップグレードしてもRichMenuなどの既存のBotに登録された情報は、そのまま維持されます。
アップグレード後もAPI 1.0でメッセージを送信することはできますが、アップグレードの際にメッセージCallbackで受信するHeaderおよびRequestBodyの形式はAPI 2.0の形式に変更されます。
そのため、メッセージCallbackで対話型コミュニケーションを行なう際は、アップグレードする前にメッセージCallbackの受信サーバー側のアプリケーションを修正する必要があります。
注意
外部ソリューションを利用するなど、Bot callback受信サーバーの利用権限がない場合、アップグレードする前に外部ソリューションを提供する開発会社にお問い合わせください。
アップグレードの事前準備
BotをAPI 2.0にアップグレードする事前準備手順は以下の通りです。
1. アプリの追加
API 2.0を利用するためには管理者がDeveloper Consoleでアプリを追加する際に、OAuth Scopesで「bot」を選択する必要があります。
詳細はアプリを参照してください。
2. Service Account認証の利用
Botアプリでは、Service Account認証を使用するため、Developer Consoleでアプリを追加する際に、Service Accountを発行します。
発行したService AccountをもとにAccess Tokenを取得し、API 2.0のBot APIを利用します。
詳細はService Account認証(JWT)を参照してください。
注意
- API 1.0の認可機能で取得したAccess TokenでAPI 2.0のBot APIを利用することはできません。必ず、API 2.0の認可機能で取得したAccess Tokenを利用してください。
- API 2.0ではAccess Token自動延長を提供しません。Access Tokenと同時に取得したRefresh Tokenを用いて、Access Tokenの再取得を行なってください。
3. メッセージ送信APIの変更
API 1.0で呼び出しているッセージ送信APIの実装箇所をAPI 2.0に変更します。 API endpoint、Request、Responseをすべて変更する必要があります。
3.1 API endpoint
例えば、トークルームを指定してメッセージを送信するAPIのendpointは、以下になります。
API 1.0
POST https://apis.worksmobile.com/r/{API_ID}/message/v1/bot/{botNo}/message/push
API 2.0
POST https://www.worksapis.com/v1.0/bots/{botId}/channels/{channelId}/messages
参考
- API 1.0の「botNo」はAPI 2.0の「botId」に相当します。同じBotであれば「botNo」と「botId」は同じです。
- API 2.0ではAPI IDは使用しません。
- API 2.0のメッセージ送信APIは送信先であるユーザーとトークルームでPathが異なります。
- ユーザー : /bots/{botId}/users/{userId}/messages
- トークルーム : /bots/{botId}/channels/{channelId}/messages
3.2 Request / Response
API 2.0のBot APIのRequest / Response形式に変更します。
詳細はAPI 2.0のBot APIのトーク共通プロパティをを参照してください。
3.3 コンテンツファイルのアップロード
参考
コンテンツファイルを利用しない場合、この手順をスキップしてください。
Botのコンテンツをアップロードする際の実装を修正します。
詳細はファイルアップロード / ダウンロードを参照してください。
4. メッセージCallbackの変更
参考
Callbackを利用しない場合、この手順をスキップしてください。
callback URLに指定されるAPI 1.0でメッセージ受信している実装箇所をAPI 2.0に変更します。
メッセージの改ざんチェックには、X-WORKS-SignatureヘッダーとBot secretを利用します。
Bot secretの値は Developer Console > Bot の詳細情報画面で確認することができます。
詳細はメッセージ(Callback) 受信を参照してください。
アップグレードの実施
稼働中のBotを停止してアップグレードを実施する場合の手順
- 「アップグレードの事前準備」を行います。
- Developer Console > BotでアップグレードするBotを選択します。
- Bot修正画面でAPI 2.0を選択します。
- [保存]をクリックするとアップグレード完了です。
稼働中のBotを稼働したままアップグレードを実施する場合の手順
- 「アップグレードの事前準備」を行います。
- Developer Console > BotでAPI 2.0用のBotを新規追加します。
- 新規追加したBotを非公開に設定し、既存Botと同じ情報を入力します。
- Callbackを利用する場合、API 2.0用のCallback URLを設定します。
- API 2.0に対応したBotシステムで使用するbotIdは新規追加したBotのbotIdを指定してテストを行ないます。
- テスト完了後、API 2.0に対応したBotシステムで使用するbotIdを既存BotのbotIdを変更します。
- Developer Console > Botでアップグレードする既存Botを選択します。
- Bot修正画面でAPI 2.0を選択します。
- Callbackを利用する場合、API 2.0用のCallback URLを設定します。
- [保存]をクリックするとアップグレード完了です。
付録 : プロパティ名変更一覧
2.0でプロパティ名が変更されたプロパティ名は以下の通りです。 一部を除く、各プロパティの値は同じです。
| プロパティ名 | API1.0 | API2.0 | 備考 |
|---|---|---|---|
| bot識別子 | botNo | botId | |
| ユーザーを特定するID | accountId | userId | |
| ユーザーリスト | accountIds, memberList | members | |
| Bot名 | name | botName | |
| 担当者 | managers | administrators | |
| 副担当者 | submanagers | subadministrators | |
| 複数人のトークルームに招待可否 | useGroupJoin | enableGroupJoin | |
| Botの利用ドメイン | domainIds | allowDomains | |
| Callback利用有無 | useCallback | enableCallback | |
| Bot名(多国語) | i18nNames[].name | i18nNames[].botName | |
| Callback発生時刻 | createdTime | issuedTime | YYYY-MM-DDThh:mm:ssTZD形式 |
| リッチメニュー名 | richMenuName | richmenuName | |
| プレビュー画像の URL | previewUrl | previewImageUrl | Image |
| 元画像のURL | resourceUrl | originalContentUrl | Image |
| ファイルアップロードで取得したID | resourceId | fileId | Image |
| カバーデータ背景画像のファイルID | coverData.fileId | coverData.backgroundFileId | List Template |
| カバーデータ背景画像のURL | coverData.backgroundImage | coverData.backgroundImageUrl | List Template |
| アイテム画像のURL | elements[].image | elements[].originalContentUrl | List Template |
| 多言語のカバーデータ背景画像のURLリスト | coverData.i18nBackgroundImages[] | coverData.i18nBackgroundImageUrls[] | List Template |
| カバーデータの言語コード | coverData.i18nBackgroundImages[].language | coverData.i18nBackgroundImageUrls[].language | List Template |
| カバーデータ背景画像のURL | coverData.i18nBackgroundImages[].backgroundImage | coverData.i18nBackgroundImageUrls[].backgroundImageUrl | List Template |
| 多言語のアイテムの画像URLリスト | elements[].i18nImages[] | elements[].i18nOriginalContentUrls[] | List Template |
| 多国語の言語コード | elements[].i18nImages[].language | elements[].i18nOriginalContentUrls[].language | List Template |
| アイテム画像のURL | elements[].i18nImages[].image | elements[].i18nOriginalContentUrls[].originalContentUrl | List Template |
| 多言語のアイテム画像のリソースIDリスト | elements[].resourceIds[] | elements[].i18nFileIds[] | List Template |
| 多言語のアイテム画像の言語コード | elements[].resourceIds[].language | elements[].i18nFileIds[].language | List Template |
| 画像URL | columns[].thumbnailImageUrl | columns[].originalContentUrl | Carousel |
| 画像のリソースID | columns[].thumbnailImageResourceId | columns[].fileId | Carousel |
| 多言語の画像URLリスト | columns[].i18nThumbnailImageUrls[] | columns[].i18nOriginalContentUrls[] | Carousel |
| 多言語の言語コード | columns[].i18nThumbnailImageUrls[].language | columns[].i18nOriginalContentUrls[].language | Carousel |
| 画像URL | columns[].i18nThumbnailImageUrls[].thumbnailImageUrl | columns[].i18nOriginalContentUrls[].originalContentUrl | Carousel |
| 多言語の画像のリソースIDリスト | columns[].i18nThumbnailImageResourceIds[] | columns[].i18nFileIds[] | Carousel |
| 多言語の画像の言語コード | columns[].i18nThumbnailImageResourceIds[].language | columns[].i18nFileIds[].language | Carousel |
| 画像のリソースID | columns[].i18nThumbnailImageResourceIds[].thumbnailImageResourceId | columns[].i18nFileIds[].fileId | Carousel |
| 画像URL | columns[].imageUrl | columns[].originalContentUrl | Image Carousel |
| 画像のリソースID | columns[].imageResourceId | columns[].fileId | Image Carousel |
| 多言語の画像URLリスト | columns[].i18nImageUrls[] | columns[].i18nOriginalContentUrls[] | Image Carousel |
| 多言語の言語コード | columns[].i18nImageUrls[].language | columns[].i18nOriginalContentUrls[].language | Image Carousel |
| 画像URL | columns[].i18nImageUrls[].imageUrl | columns[].i18nOriginalContentUrls[].originalContentUrl | Image Carousel |
| 多言語の画像のリソースIDリスト | columns[].i18nImageResourceIds[] | columns[].i18nFileIds[] | Image Carousel |
| 多言語の画像の言語コード | columns[].i18nImageResourceIds[].language | columns[].i18nFileIds[].language | Image Carousel |
| 画像のリソースID | columns[].i18nImageResourceIds[].imageResourceId | columns[].i18nFileIds[].fileId | Image Carousel |
| 元ファイルがあるURL | resourceUrl | originalContentUrl | File |
| コンテンツアップロード後に取得したリソース ID | resourceId | fileId | File |