Cisco Webex Teams(旧Cisco Spark)の開発者サイトの使い方

> 2018.05.22. Cisco Webex TeamsからCisco Webex Teamsへの名称変更に伴い、記載内容を変更しました。

## この記事では、以下に関して記載しています
* 『開発者トークン』に関する重要な注意点
* Cisco Webex Teamsの開発者サイトで出来ること
* Cisco Webex Teamsの開発者サイトにログインが必要なとき、そうでないとき
* APIリファレンスに関すること
* 実際にAPIが簡単に試せるテストモードに関すること

# 1. Cisco Webex Teamsの開発者サイト

## 1.1. まずは注意点から

Cisco Webex Teamsの開発者サイトにログインすると、
自動的に『**開発者トークン**』なるものが発行されます。

この『開発者トークン』は、**開発・テスト時のみ利用**するようにしましょう。
このトークンは、**ログイン中の開発者サイトのいろんな場所で表示される**ので、
**絶対に誰にも見せない**ようにしましょう。

![トークンは誰にも見せないこと](https://qiita-image-store.s3.amazonaws.com/0/211666/233d6a62-bd71-f2f4-58b2-a2d025dc1e72.png)

"**開発者トークン** ≒ **Cisco Webex Teamsユーザのアカウントとパスワード**"
であるので、開発者トークンが流出すると、
該当のユーザがアクセスできる情報や、該当のユーザで可能な操作を、
APIを使って可能になります。
**「開発者トークンの流出」は、「該当Cisco Webex Teamsユーザのアカウントとパスワードが共に流出」とほぼ同じ意味**なので、
慎重になる必要があります。

開発者サイト上での作業が終わった後は、
**必ず明示的に開発者サイトからログアウトして、開発者トークンを無効**にしましょう。
APIリファレンス閲覧時などはログアウト状態でOKです。
**開発者サイト上の右上のユーザアイコンクリック後の、[Log Out]リンクから明示的にログアウト**できます。

**『開発者トークン』は開発者サイト上で遊ぶときだけ使って、
実際の開発時には、アプリケーション用のトークンである、
Botアカウントのトークンや、OAuth2で取得したトークンなどを利用**するようにしましょう。
これらのトークンの発行方法に関しては、別の記事で紹介します。

## 1.2. Cisco Webex Teamsの開発者サイトに行ってみる

[Cisco Webex for Developers](https://developer.webex.com/) ([https://developer.webex.com/](https://developer.webex.com/))が、
Cisco Webex Teamsの開発者サイトです。


今のところ全編英語のみになってますが、
APIリファレンスに関しては、英語アレルギーな私が吐き気しないレベルなので、
結構なんとかなる感じだと思います。
やや細かい話が、やや長文で書かれているガイド部分は、まあアレですが、
その辺は、今後記載する記事でなんとか補完していこうと思います。

Cisco Webex Teamsに関連する開発者向けのだいたいの情報はここで入手できます。
一部の機能は、Cisco Webex Teamsのアカウントを使って開発者サイトにログインが必要ですが、
**必要なければログインしない、積極的にログアウトする**方針でいきましょう。

### ■ 開発者サイトにログインしなくてもできること

* APIリファレンスの閲覧。
* 開発ガイド(機能の説明とか、やや細かい話とか)の閲覧。
* ブログ記事の閲覧。
* メールによる開発サポートへの連絡(英語でのやりとり)。

### ■ 開発者サイトにログインが必要なこと

* Botアカウントの作成。
* OAuth2を利用するアプリケーションの登録。
* 開発者サイト上でAPIの実行を試す。
* Cisco Webex Teams上の開発サポートスペースへの参加(一般には英語でのやりとりだが、  
  オープンなコミュニティなので日本語読める人がいれば、日本語でも回答もらえるかも？)。


# 2. Cisco Webex Teamsの開発者サイトのテストモードで遊ぶ

**2017年11月21日ごろ時点でのリンク名とかで書いていますが、
サイト側の更新によって微妙に変わるかもしれないので、適当に読み替えお願いします。**

無償のCisco Webex Teamsアカウントを利用して開発を進めることができます。

## 2.1 APIでスペースを作ってみる

とりあえず、APIを開発者サイト上で実行して、
Cisco Webex Teams上にスペースを作成しようと思います。

1. [Cisco Webex for Developers](https://developer.webex.com/) ([https://developer.webex.com/](https://developer.webex.com/))に行きましょう。
1. 画面右上に[Log In]ボタンがあるはずなので、そこからログインします。
  Cisco Webex Teamsのクライアントにサインインするのと同じアカウントです。
1. 画面上側に、[Docs]リンクがあるはずで、そこから開発ガイド、APIリファレンスなどに行けます。  
  **ログイン中は、いろんな画面でAPI実行が試せるようになっていて、  
  いろんなところに開発者トークンが表示されます。  
  実際に動作するトークンなので、トークン見られないように気を付けてください。**
1. [WEBEX TEAMS API]がAPIの一覧です。  
  Cisco Webex TeamsのメッセージングAPIは、  
  RESTベースのWeb APIで、httpsでGET, POST, PUT, DELETEメソッドを使って、  
  クラウド上のCisco Webex TeamsのAPIサービスとやりとりすることになります。
1. [WEBEX TEAMS API] > [Rooms] > [Create a Room]あたりに移動してみます。  
  **Cisco Webex Teamsのクライアント側で「スペース」と呼んでいるものが、APIの「Room」に該当します。**  
  歴史的経緯(割愛)があって、「Room」->「スペース」に名称が変更されていますが、APIはそのままです。
1. ページの上の方に、[Test Mode]の[ON/OFF]スイッチが表示されているはずなので、[ON]にしましょう。  
  **表示されない場合は、ブラウザのウィンドウを大きめに広げて表示してから、  
  今一度、ページに移動しなおすと表示されるはず**。
1. **[Test Mode]が[ON]の状態では、[Authorization]に、開発者トークンが表示されているので、  
  見られないように、いったん、気を引き締めましょう**。
1. [Request Parameters]項目に[title]フィールドがあって、  
  テキストボックスに入力できるようになっているはずなので、  
  作りたいスペース名を適当に入力しましょう。
  「はじめてのWebex Teamsスペース」とかなんでもいいです。
1. ほかのフィールドに薄っすら表示されているのは入力例なので、
薄っすら状態では、利用されません。
今回は、[title]だけあればOKなので、ほかのフィールドはノータッチで！！
1. [Run]ボタンを押すと、実際にWebex TeamsのREST APIが実行されます。
1. ページ右側に[Request]と[Response]のBodyの内容が表示されます。  
  **これは実行例ではなく、実際のリクエストとレスポンスを成形したものです**。  
  ログアウト状態では、ここには実行例が表示されます。
1. Cisco Webex Teamsのクライアントアプリを確認しましょう。  
  **実際にスペースが作成されている**はずです。

## 2.2. レスポンスを確認する

ページ右側に表示されたレスポンスのBodyはこんな感じになっているはずです(一部ID系はマスクしています)。
次の手順で利用するので、"id"の値(以下の場合は、`Y2lzY29zcGFyazovL3VzL1xxxxxxxxxxx`)をコピーして覚えておきましょう。
**これは作成されたスペースを一意に表すID**になります。

```json
{
	"id": "Y2lzY29zcGFyazovL3VzL1xxxxxxxxxxx",
	"title": "はじめてのWebex Teamsスペース",
	"type": "group",
	"isLocked": false,
	"lastActivity": "2017-11-21T08:36:14.981Z",
	"creatorId": "xxxxxxxxxxxxyyyyyyyyyyyy",
	"created": "2017-11-21T08:36:14.981Z"
}
```

## 2.3. 作ったスペースにAPIでメッセージを投稿してみる

1. 開発者サイトにログインしたまま、かつ、[Test Mode]が[ON]の状態で、  
   [WEBEX TEAMS API] > [Messages] > [Create a Message]に移動します。
1. [Request Parameters]項目に[roomId]フィールドがあるので、  
 テキストボックスに先ほどコピーしておいた、**スペースのID**をペーストしましょう。
1. [text]フィールドに、投稿したいメッセージを適当に入力します。  
  「はじめてのメッセージ」とかなんでもいいです。
1. ほかのフィールドに薄っすら表示されているのは入力例なので、  
  薄っすら状態では、利用されません。  
  今回は、[roomId]と[text]だけあればOKなので、ほかのフィールドはノータッチで！！
1. [Run]ボタンを押すと、実際にWebex TeamsのREST APIが実行されます。
1. ページ右側に[Request]と[Response]のBodyの内容が表示されます。  
1. Cisco Webex Teamsのクライアントアプリを確認しましょう。
  **実際にスペースにメッセージが投稿されている**はずです。

## 2.4. DELETEは特に慎重に！

このように、開発者サイトと[Test Mode]使って、Cisco Webex Teamsの開発者サイト上で、
APIを実行して試すことができます。
**疑似的に動いているのではありません！**
**リアルな世界で動いているので、**
**DELETE**すると、該当の開発者のトークンで消せる範囲の情報が、
**本当に消えるので注意**です。

もちろん、DELETE以外も実際の世界で動作するので、慎重に行う必要はあります。

「開発者トークン」が実行できる処理は、開発者サイトにログインしたアカウントのユーザと同等です。
該当ユーザが参加している任意のスペースにメッセージを投稿したりできますが、
**実運用でこの開発者トークンは利用しないようにしましょう**。

# 3. 遊び終わったらログアウトを！！

**開発者右上のユーザアイコン部分を押すと、[Log Out]リンクが出てきます。
「開発者トークン」が無効になる趣旨のメッセージが表示されますが、迷わず、
[Log Out]ボタンを押してログアウトしましょう！！**

# 4. 次のステップ

テストモードは所詮はお遊びです。
**開発者トークンで、開発を進めるべきではありません**。
**開発を始めるには、アプリケーション用のトークンを発行**しましょう。

本記事執筆時点(2018年01月30日時点)では、

* アプリケーションを登録して、OAuth2でトークンを発行する方法
* Bot用アカウントを作成して、トークンを発行する方法

があります。

Bot用アカウントを作成する方法の方が簡単なので、
まずはこの方法から始めてみるのがおススメです！

Bot用アカウントの作成方法は、[こちらの記事](https://qiita.com/thrzn41/items/672870bb8a6ab2ca44b2)を参照ください。