はじめに

これまでに G Suite ほか Google 系、Slack、Salesforce、Box、Docusign、Facebook、twitter、twilio、Stripe、UiPath、kintone、Backlog、Chatwork、freee 等々、様々なクラウドサービスと自社のクラウドサービスの REST API 連携について調べてきました。その多くを記事にまとめています（Qiita の記事ではないですが）。

https://questetra.com/ja/author/kusaka0211/
※この記事一覧には API 連携に関係ないものも一部含まれています

その中で Microsoft 365 / Office 365（以下、M365/O365）のサービス（Teams/SharePoint Online/OneDrive/Excel Online/Outlook）の REST API との連携については、だいぶ苦労しました。REST API 連携については、かなり経験値を持っていると思うのですが、それでもかなり苦労をしましたので、M365/O365 の API は相当手強い、と思っています。これから M365/O365 の API を使う人が少しでもハマらないようにと、注意すべきポイントをまとめました。

注意すべきポイント

その1：API のバージョンや種類がたくさんある

・同じサービスに対する API の種類・バージョンがいくつかある

API のバージョンが変わるということは別に珍しくありません。どのサービスでもある話です。

ただ M365/O365 については

　・認証のエンドポイントの名称が変わった、バージョンが変わった
　・API の名称が変わった、バージョンが変わった

ということがあり、Web 検索してたどりついた記事がどれについてのものか意識していないと、混乱します。いくつかの記事を見比べていると、前提が異なっているために、内容が合わないということが少なくありません。

例えば、2020/9/5現在で、「office365 api」と検索すると、最初にヒットするのは以下のページでした。

実はこのページは古い API についてのページです。よく見るとページの上部に「以前のバージョン」とパンくずがあります。が、よほど注意していないと気付けないかと思います。よく見れば URL にも previous-versions と入ってます。

また、「outlook 予定表 api」で検索すると、最初にヒットするのは以下のページでした。

それより後にヒットするのが以下ページでした。

前者は「Outlook REST バージョン2.0」、後者は「Microsoft Graph REST API v1.0」についてのページです。どちらが新しいのか・・・後者です。ページの日付を見ると、前者は2018/06/30、

後者は2020/04/15になっています。

バージョン数値の多い前者が新しい方か？と思ってしまったのですが、違いました。Graph API の方が新しいと知っている人にとっては当たり前の話かもしれませんが、知らない側から見ると日付に注意するしかありません。

・認証のエンドポイントの種類・バージョンがいくつかある

認証のエンドポイントについても、私が知るだけでも3種類あります。

　・AzureAD v2.0 endpoint
　・AzureAD v1.0 endpoint
　・AzureAD Access Control

各々のページでこのエンドポイントのバージョンに触れている記述は少ない（あちこちに書かれていてもややこしいとは思います）ので、エンドポイントの URL でどれに対応した説明かを見極める必要があります。

AzureAD v2.0 endpoint の URL は以下です。

認可エンドポイント URL：https://login.microsoftonline.com/{tenant}.onmicrosoft.com/oauth2/v2.0/authorize

トークンエンドポイント URL：https://login.microsoftonline.com/{tenant}.onmicrosoft.com/oauth2/v2.0/token

エンドポイントが複数ある、ということを意識して注意してください。

上記3つの違いについて、詳しくは以下の記事にまとめています。

「Office365 とクラウド型ワークフローとの連携方法について」
https://questetra.com/ja/blog/office365-questetra-201707/

・機能的に似た API で位置付けの異なるものがある

Outlook の予定の追加の方法を探すと、検索でまずひっかかったのは以下ページでした。

POST /groups/{id}/events

実は上記はグループ向けの予定に関するもので、ユーザ向けは以下ページです。

POST /me/calendars

はじめは前者のページを見ていて、なぜ group の id が必要なのか理解に苦しみました・・・この違いに気づくためには左にあるインデックスを確認する必要があります。

こちらがグループ向けのページのインデックスで

こちらがユーザ向けのページのインデックスです。

そもそも見るべきページが違っていただけなのですが、そういう機能のものが複数あると想定していないと気付きにくいです。

その2：ほしい id がアクセス URL に含まれていない

例えば、Google Sheets や Google Drive や Box とかだと、API で使うフォルダ id やファイル id はアクセス URL に含まれています。ですので、id を特定するのはそれほど難しくありません。
一方で OneDrive や Excel Online の場合、アクセス URL には含まれていません。API を何度もたたいて調べる必要があります。
例えば、Excel Online の場合は以下のようにたどる必要がありました。ファイル id を得るまでだけで結構苦労しました。詳しくは以下の記事にまとめています。

「Excel Online へクラウドワークフロー Questetra からデータ出力する方法（API 連携の設定手順）」
https://support.questetra.com/ja/developer-blog/excel-online-questetra/

その他にもいくつか

以下の2点は、そういう流儀なんだと知っておくといいと思う点です。

・URL の id にはすぐ手前の項目の id を入れればよい

例えば、Outlook 予定表の取得（グループの方）は以下 URL となっています。

GET /groups/{id}/events/{id}

それぞれの id に何を入れるの？と戸惑いました。前の id には group の id が、後ろの id には event の id が入ります。
他サービスで親切なドキュメントですと、

GET /groups/{group-id}/events/{event-id}

といった感じで書いてくれているのですが・・・注意してください。

・HTTP メソッドで処理を切り替える

GET/POST/PUT/PATCH/DELETE と HTTP メソッドで処理を切り替えるのが基本的な考え方のようです。
これは他サービスでもあるケースですが、HTTP メソッドでは切り替えずに URL やパラメータで切り替えているサービスも少なくありません。また、これがわかっていると、とりあえずデータのフォーマットを確認したい場合に GET で取ってみよう、と考えることができます。

まとめ

●注意1●：Web 検索でひっかかった記事は日付と位置づけをしっかり確認しましょう

●注意2●：処理に必要な id を取るところから処理を考える必要があると考えておきましょう

他のサービスの場合、ドキュメントがわかりやすく整備されていて、検索でヒットしたものを見ることで、だいたいやりたいことが実現できます（そもそもここまで対象範囲が広くないという差もあるとは思います）。が、M365/O365 の場合は新旧のドキュメントが混在していて、とても慎重にならないといけない、また API を使うときに結構手間がかかることが多い、と覚悟して臨むことをおすすめします。

決して M365/O365 の API をディスりたい訳ではありません。自社クラウドサービスと連携して使われることも多く、重要な連携相手だと思っています。ただ、いろいろ手強い、ということを共有しておくことに意味があると考えている次第です。

少しでも役に立てば幸いです。