本機能はAdvanceプラン以上で利用可能となります。
この記事の概要
Connector Builderを使ってカスタムコネクタを作ろうとした際の設定で必要になる概念を解説するものです。
具体的な設定方法についてはドキュメント「カスタムコネクタを作成する」に記載がありますが、これだけでは理解が難しい場合に合わせて読んでいただけるものとしています。
対象とする方
API操作に慣れていない、あるいは初めてである非エンジニアの方を想定しています。
Connector Builderを利用する上でおさえると良い概念
下記3つの概念・仕様の理解を深めると、実際の設定もスムーズになっていきます。
- REST APIの仕様
- 認証の仕様
- JSONの仕様
カスタムコネクタは下図の様な概略構造で動作します。
カスタムコネクタから「REST API」にリクエストが行われ、同時に「認証」が行われます。
REST APIは単にAPIと呼ばれる事が多いため、以降「API」と表記します。
認証がOKであれば、「API」はそのサービスのデータベースからデータを取得し、「JSON」という形式でカスタムコネクタに返す、という具合です。
以降、これらの3つの概念を順に説明していきます。
1. REST APIとは何か
1-1. 概念
カスタムコネクタでは、データ取得を行いたいサービスのAPIを利用します。
APIとはApplication Programming Interfaceの略で、簡単に表現するとシステムが別のシステムからデータを引き出したり、追加・更新したり、削除したりするための窓口として機能する概念です。
厳密には上記の操作を使うための決まりごとを指すものなのですが、「窓口のことである」とイメージした方が解りやすいです。
1-2. エンドポイントURLとベースURL
APIにはWEBサイトと同じ様に、それにアクセスするためのURLが存在します。
これをエンドポイントURLと呼びます。
APIの中で特定機能の窓口を指す完全住所の様なものだと考えていただいて差し支えありません。
エンドポイントURLは下記のパーツで構成されています。
| ベースURL | APIのURLで共通になるもの。 |
|---|---|
| パス | APIで利用できる機能によって変化します。 上記例では、TROCCOのAPIでユーザー情報を取得するためのものになっています。 例えば、他に/api/jobs（転送ジョブを取得）、/api/data_mart_definition（データマート定義を取得）などがあります。 |
| パラメータ | エンドポイントに対して条件を指定する様なパーツです。 上記例だと「?limit=50」が該当し、取得できるデータのうち50行までを返すという指定になっています。 ちなみに、本例の様にURLに直接条件が指定されるようなものをクエリパラメータと呼びますが、URL上に見えない形で通信に含める手法もあります。 |
1-3. エンドポイント情報はどこで探せば良いのか？
対象システムの「APIリファレンス」には、通常これらの情報一式が記述されています。
下記はTROCCOのAPIリファレンスでの記載例です。
構成は製品によって異なりますが、概ね使いたい用途のAPIリファレンスにはベースURLやパス、パラメーターを含む情報が掲載されています。
1-4. ページネーションの概念
データ取得系のAPIを利用する上で、もう一つ知って欲しいのが「ページネーション」の概念です。
例えばニュースサイトを見ている時に記事の一覧を見ているとします。
ニュース記事は膨大に存在するため、2ページ目・3ページ目と続いていく事も普通であると思います。
これはデータ取得系のAPIにも同じく言える事で、50件ずつ返す・100件ずつ返すなどAPI毎に仕様が異なっています。
具体的なイメージは、後述の「JSONの仕様」の項目で説明します。
1-5. 実際のカスタムコネクタ設定画面
カスタムコネクタ新規作成の画面に入ると、コネクタ情報のセクションが出てきます。
ここで、先ほどのベースURLを記載します。
エンドポイントの設定画面では、パスやパラメータを記入していきます。
1.6 さらに詳細に知りたい方へ
こちらの記事にREST API単体について解説していますので、ご覧下さい。
2. 認証について
2-1. API KeyとOAuth2の概要
SaaSサービスがユーザーのログインを経て使える様になるのと同じく、APIを利用することにも同じ様に認証を行う必要があることがほとんどです。
認証がないと建物の鍵を開けっぱなしにする様な状態になってしまうため、APIを利用する際はユーザーからは見えにくくいところで鍵を入れて開ける様な動作が行われます。
ここでは簡単に2種類の認証方法について説明します。
| APIキー | サービスから発行されている鍵になる文字列を使って認証を得る方式です。 簡単に表現すると、会社の物理的な鍵をそのまま渡す様な方式です。 |
|---|---|
| OAuth2 | 「オーオースツー」と読みます。 APIキーと対照的に、鍵そのものを渡さずに権限と期限を制限した一時的な鍵を渡すような方式です。 |
2-2. API Keyの解説
API Keyの場合はとてもシンプルです。
ある会社があるとして、会社のオーナーが誰かに物理的な鍵を渡しているイメージです。
鍵をもらった人（ユーザー）は当然ながら会社のドアを開けることが出来ます。
利用したいAPIのサービスメニューに「API Key（あるいは外部キー）」の設定に関する機能を探すか、サービス管理者に問い合わせてみてください。
2-3.OAuth2の解説
OAuth2は非常に良くできた仕組みですが、とても複雑です。
深くまで理解できなくても問題ありませんので、「直接鍵を預かる事なく、カスタムコネクタ（TROCCO）と対象のサービスでうまい事セキュアにやりとりが出来るんだな」という事だけまずは押さえてください。より詳細な解説は本記事の最後に掲載します。
実際のサービスに対してOAuth2認証をできる様にするためには、対象サービスに対してクライアント登録（TROCCOの情報を登録する）という操作が必要です。
このクライアント登録を完了すると、下記の様な情報が払い出されます。
カスタムコネクタの「認証方式」をOAuth2に設定し、接続情報設定画面で必要な情報を入力しましょう。
クライアント作成は対象サービスの管理者権限が必要な事が多いです。
利用しているサービスの管理者へ問い合わせてみてください。
TROCCO公式コネクタでは、あらかじめTROCCOが対象サービスへクライアント登録を行っており、ユーザーがこの登録操作をする必要なくOAuth2認証を利用することができます。この点が公式コネクタとの違いです。
3. JSONの仕様
3-1. JSON（JavaScript Object Notation）の概要
簡単に表現するとデータを記述するための記述フォーマットの一つです。
例えばprimeNumberという会社のデータを表現するJSONがあったとしたら次の様な形になります。
上記のデータがリクエストの結果で得られた場合、$.nameの様な形でアクセスすると「株式会社primeNumber」という値だけを取り出すことが出来ます。
TROCCOのコネクタやカスタムコネクタでも、この仕様を使って大量のデータをAPIから取得していきます。
3-2. APIから返ってきたデータ本体がどこかを特定する
APIから返ってきたJSONの中にはその通信が成功したか失敗したかの情報や、APIから添えられているログメッセージなども含まれていることが多いです。
この中にデータ本体が入っている箇所があるので、これを特定しましょう。
下図の例だと、配列（[ ]かっこで括られた、人の情報の塊が複数コンマ区切りで入っている）で表現されている部分となります。
*上記データイメージはサンプルです。実際にAPIから返ってくるJSONの形は、サービスにより異なりますのでご注意下さい。
この配列には、「data」という名前が付けられている様です。
そのためカスタムコネクタで設定を求められる「JSONPathルート」という部分では「$.data」と指定すると、うまくデータ本体を読ませることができます。
3-3. ページ・ページネーションの解説
続いて、先ほどのデータ部の次にあった「pagination」という部分についての解説です。
先ほどと同じJSONを例に説明します。
項目それぞれは、次のことを意味しています。
- current_page: 1・・・現在1ページ目にいること
- total_pages: 5・・・全件をper_pageの件数ずつに分けた場合、最大で5ページあるということ
- total_count: 47・・・条件に一致するデータ件数は全部で47件あるということ
- per_page: 10・・・1ページにつき10件ずつ表示・取得する設定ということ
上記の様な例の場合は、APIのパラメーター側で現在のページを指定していることが多いです。
カスタムコネクタのページング設定セクションでは、例として次の様な設定となります。
さいごに
これまでにAPIを使ったことがない方にとっては、新たな概念が多く大変だったと思います。
しかし、さまざまなサービスのAPIを利用してデータを自動取得できる様になるとデータ利活用の幅が大きく広がります。
次ステップとして「カスタムコネクタを作成する」に進んでいただき、実際にカスタムコネクタを作成してみてください。
あるいは、カスタムコネクタの作成事例も参考になると思います
こちらもあわせてご覧ください。
カスタムコネクタの作成事例
補足：OAuth2のより詳しい解説
OAuth2にはいくつか種類があります。
下図を使ってOAuth2の中の「認可コード」方式について、図書館と利用者の関係で解説します。
前提として、図書館のオーナーである田中さんはあらかじめ山田さんに利用者コードを与えています。いわゆる会員証と会員番号みたいなものだと思ってください。
流れを書き起こすと、下記の様な具合になります。
- 山田さんは図書館の受付に自分のアクセスしたい資料についてリクエストします。
- 受付は山田さんの会員情報を照会し、図書館のオーナーである田中さんに内容を確認します。
- オーナーの田中さんは、山田さんに見せて良い資料の範囲とその時間制限を受付に指示します。
- 受付はオーナーの指示から一時入館証を得るためのパスワードを作成し、それを山田さんへ渡してあげます。
- 山田さんは、受け取ったパスワードで一時入館証を入手し、目的の資料を閲覧して情報を入手し帰って行きました。
- 1時間後、一時入館証は自動的に期限切れでただのカードとなりました。
API Keyと比べて、かなり複雑なことをやっている印象があると思います。
しかし次の様なメリットがあります。
✅ 会社の鍵そのものを渡すわけではないため、漏洩してもリスクが少ない
✅ 会社のオーナーは誰に対して鍵を渡すかも厳密にコントロールできる
カスタムコネクタの話に置き換え直すと、下記の様になります。
- 山田さん・・・カスタムコネクタ（TROCCO）あるいはあなた自身であり、クライアントを指します。
- 利用コード・・・クライアントシークレットを指します。
- オーナーの田中さん・・・あなたがデータを取得したい利用サービスの管理者。
- 受付の方が渡した一時パスワード・・・認可コードと呼ばれるものです。アクセストークンとの引き換え証になります。
- 資料・・・取得したいデータそのもの。
- できること・・・スコープ。今回だと特定の資料群にアクセスできる権利のこと。
以上、OAuth2の中でも代表的な「認可コード」方式の補足解説でした。
