目次


連載: IBM Watson Workspace #鬼わか アプリケーション開発

第 2 回: GraphQL API Explorer の使い方 #鬼わか 解説

Comments

コンテンツシリーズ

このコンテンツは全#シリーズのパート#です: 連載: IBM Watson Workspace #鬼わか アプリケーション開発

このシリーズの続きに乞うご期待。

このコンテンツはシリーズの一部分です:連載: IBM Watson Workspace #鬼わか アプリケーション開発

このシリーズの続きに乞うご期待。

1

はじめに

連載: IBM Watson Workspace #鬼わか アプリケーション開発」にアクセスいただきどうもありがとうございます。第 1 回目の記事を読んで実際に IBM Watson Workspace (以下、WWS と表記)と連携可能なアプリケーションの開発に興味を持たれたのではないかと思います。連載第 2 回目となる今回は GraphQL API Explorer について #鬼わか 解説をします。

アプリケーションの開発を行う際に、実現したいアプリケーションのイメージと用意されている API との間にギャップがあり思うように開発が始められない、実装を始めたものの想定している事が実現できずに頓挫してしまった、といった経験は無いでしょうか?そのような事態を避けるために、WWS では IBM Watson Work Services (以下、Watson Work Services と表記) によって提供されている API をプログラムレスですぐに試すことができる GraphQL API Explorer と呼ばれるツールを提供しています。GraphQL API Explorer はプログラムを一切書かずに API をすぐに評価する事がでるツールで、各 API で設定可能な細かいパラメーター設定を評価する事ができます。実際にパラメーターを設定した状態で、 API が実行された時のレスポンスをすぐに確認する事ができます。

連携アプリケーションの機能を思い浮かべたときに、用意されている API で想定されている機能が実現できるかすぐに確認できるので、アプリケーション開発の効率化の向上を強力に支援します。

アプリケーション開発に興味がある場合、まずは GraphQL API Explorer を利用して Watson Work Services が提供する API によってどのような事ができるかを把握してみてください!

2

IBM Watson Workspace API の概要

WWS では「Watson Workspace Services」によって様々な API が提供されています。API を利用して開発を行うことで WWS の機能を拡張する、他のアプリケーションとの連携する、などが実現可能になります。Watson Work Services では以下のような 3 種類の API が提供されています。いずれも HTTP プロトコルを利用した Web API 形式になっています。

1. REST API - WWS 上のデータの作成や取得をサポートしています。メッセージの投稿や認証処理などは REST API でのみ可能です。

2. Webhook API - WWS 上で発生したイベント (例:メッセージが投稿された) をトリガーにして指定した URL にデータを Post する仕組みです。WWS 上で発生する下記のイベントを利用できます。

表 1. Webhook API の種類
スペースspace-members-addedスペースにメンバーが追加された
space-members-removedスペースからメンバーが削除された
メッセージmessage-createdメッセージが追加された
message-deletedメッセージが削除された
Annotation (注釈)message-annotation-addedannotation が追加された
message-annotation-editedannotation が編集された
message-annotation-removedannotation が削除された

3. GraphQL API - 2012 年に Facebook 社が開発した API 問い合わせ言語で、REST API を拡張して、より使いやすくしたものです。WWS では GraphQL API Explorer と呼ばれるツールで実行結果をすぐに確認することが出来ます。具体的には下記のような処理が可能です。

表 2. GraphQL API の種類
スペース関連スペースを作成する
スペースのメンバーを取得する
スペースのメンバーを変更する
スペースの一覧を取得する
スペースを削除する
会話関連スペースの会話を取得する
メッセージ関連メッセージを取得する
Annotation 関連Focus をつける
3

GraphQL API Explorer の利用方法

3-1. GraphQL API Explorer の使い方

Watson Work Services には GraphQL API Explorer という、簡単に API を試す事ができるツールが用意されています。

ここに試したい GraphQL を記述し、上にある ▷ "再生ボタン" を押すことによって GraphQL API を試す事が可能になります。また API を実行した結果が右側のペインに表示されるようになっています。

GraphQL API Explorer のページ右上の "Docs" をクリックし、左のメニューから GraphQL API をクリックすると具体的にどのような GraphQL API が用意されているか確認できます。

3-2. WWS へのスペース作成と取得

では早速 GraphQL API Explorer を使って WWS 上に "鬼わか Space" という名前のスペースを作成してみましょう。Watson Work Services のドキュメント内にある Create a Space が参考になります。

Create a Space の例にあるコードを左側のペインにコピー&ペーストして、title を "鬼わか Space" に変更します。その後、画面上部にある "再生ボタン" を押すと、生成されたスペース "鬼わか Space" の id が右側ペインに実行結果として表示されます。このスペース ID をキーに、"鬼わか Space" を特定することで、スペースに対する処理 (メンバーの変更、メッセージの取得等) を行えます。

図 1. スペースの作成

 

さて、"鬼わか Space" は本当に作成されているのでしょうか。WWS を開いてみると、スペース一覧に "鬼わか Space" が表示されていることが確認できます。

では既存スペースのスペース ID はどのように取得できるのでしょうか?

Watson Work Services のドキュメントの Get a list of spaces が参考になります。

Get a list of spaces の例にあるコードを左側のペインにコピー&ペーストし、今回はスペースタイトルとスペース ID を取得できればよいので、items として title と id のみ残して、不要なコードは削除します。その後、画面上部にある "再生ボタン" を押すと、右側ペインに自分がメンバーとして登録されているスペースタイトルとスペース ID が一覧され、必要なスペースの id を確認できます。

図 2. スペース情報の取得

 

3-3. スペースへのメンバーの追加とリスト取得

このセクションでは、先程作成したスペース ”鬼わか Space” にメンバーを追加してみます。

メンバーの追加には updateSpaceAddMembers を使用しますが、スペース及びメンバーの ID が必要となります。スペース ID は、3.2 で控えておいたものを使用します。メンバー ID は、getProfile で email を引数に取得する必要があります。

図 3. プロフィール情報の取得

 

スペース ID とメンバー ID が用意できたら、実際に updateSpaceAddMembers を使ってメンバーを追加してみましょう。

updateSpace の id 指定部分にスペース ID を記載し、members に メンバー ID を指定します。また今回はメンバーの追加なので、memberOperation を ADD にします。

図 4. スペースにメンバーの追加

 

これを実行した後、実際に WWS でスペースを見てみると、メンバーが追加されていることがわかります。

スペースに所属するメンバー一覧を取得するにはどのようにしたら良いでしょうか?それには getSpace を使用しスペース ID を渡すことでメンバー情報 (ID, e メール, 表示名等) を取得します。

図 5. スペースの情報取得

 

このように API を使用することで、メンバーの追加やメンバー一覧の取得を簡単に行えます。

3-4. メッセージの読み込み

最後に、GraphQL API を使用して、”鬼わか Space” に投稿されたメッセージの取得をしてみましょう。

Watson Work Services のドキュメントの View the conversation in a space のコードを、GraphQL API Explorer にコピー&ペーストします。

"conversation-id" となっているところは、メッセージ投稿先のスペースの ID (3.2 で取得したもの) に置き換えます。

図 6. 会話の情報を取得

 

サンプルコードそのままだと、以下の情報が取得できます。 () 内は、サンプルコード内のプロパティとの対応を示しています。

  • スペースの ID (id)
  • スペース作成日時 (created)
  • スペース最終更新日時 (updated)
  • 投稿されたメッセージのうち、最新 50 件 (first:50) の内容 (content) 、形式 (contentType) 、Natural Language Understanding で分析された結果 (annotations)

例えば、一番古いメッセージの本文のみを取得したいときは、下図のようにコードを変えてください。

図 7. スペース内の最後のメッセージを取得

 

その他には、以下のようなプロパティがあります。

<取得可能な情報>

  • スペースの作成者 (createdBy)
  • スペースの最終更新者 (updatedBy)
  • ページ情報 (pageInfo)

<指定可能な条件>

  • 指定した日時よりも前のメッセージ (mostRecentTimestamp) ※long 形式で指定
  • 指定した日時よりも後のメッセージ (oldestTimestamp) ※long 形式で指定
  • 指定したカーソルよりも後のメッセージ (before)
  • 指定したカーソルよりも前のメッセージ (after)

「before」「after」を使いたいときは、まず「pageInfo」で基準とするメッセージのカーソル情報を取得し、その前を何件/後を何件という風に指定します。

例えばいま、"鬼わか Space" に以下の 5 つのメッセージが投稿されていたとします。

① テストのメッセージ 1 です
② テストのメッセージ 2 です
③ テストのメッセージ 3 です
④ テストのメッセージ 4 です
⑤ テストのメッセージ 5 です

そこに対して、以下のように「pageInfo」プロパティを指定した上で最新 3 件のメッセージを取得する Query を実行すると、メッセージ ③ ④ ⑤ の情報と、メッセージ ③ のカーソル情報=「endCursor」、メッセージ ⑤ のカーソル情報=「startCursor」が取得できます。

図 8. カーソル情報の取得

 

この情報を使って、例えば、メッセージ ③ よりも前の最新メッセージ 1 件 (つまりメッセージ ②) を取得するとしたら、以下のような Query を実行します。

図 9. カーソルを利用して指定した位置のメッセージを取得

 

このように、様々な条件をつけてメッセージの取得を行うことができます。色々試してみてください。

4

まとめ

今回は WWS のアプリケーション開発の鬼への最初のステップとして、GraphQL API Explorer の概要、そして利用方法についてご紹介しました。GraphQL API Explorer を利用すれば、いきなりコーディングで試行錯誤を行わずに容易にアプリケーションで使用する API の動作を確認できることがおわかりいただけたと思います。

いよいよ今後は実際にアプリケーションを開発してみましょう!

この記事に「いいね!」と感じた方は、ハッシュタグ「 #鬼わか 」をつけて是非共有してください。

次回の記事は開発の準備をするためにアプリケーションを登録する方法について鬼わかりやすく解説いたします。お楽しみに!


ダウンロード可能なリソース


関連トピック


コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Lotus
ArticleID=1059704
ArticleTitle=連載: IBM Watson Workspace #鬼わか アプリケーション開発: 第 2 回: GraphQL API Explorer の使い方 #鬼わか 解説
publish-date=04062018