はじめに
SharePoint の API 使いたい、と思って Microsotのドキュメントを確認すると、こんな記載があります。
REST を使用して SharePoint リソースにアクセスするには、目的のクライアント オブジェクト モデル API に対応する OData 標準を使用して、REST 対応の HTTP 要求を作成します。次にその例を示します。
GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
で、accessToken はどうやって取得するのか。
- クライアントの登録はどうやって行える？
- 認可エンドポイントやトークンエンドポイントの情報は？
これが、なかなか、手こずりました。
同じように将来の自分が再び手こずる予感がするのでメモ残しておきます。
参考になれば幸いです。
本記事は【前編】です。 クライアント登録を行い client_id と client_secret を取得 & 利用するスコープを登録する方法を記しています。 認可コードフローでtokenを取得する部分の一連の方法は【後編】を参照ください。
【後編】 の記事はこちら
1. サイトURLを確認する
Microsoftのドキュメントを見ると、ところどころで {site_url} とか <site collection url> とか <SharePointWebsite> と書かれています。これは、操作を行いたいSharePointサイトのURL（パス部分も含む）です。
例えば、ルート サイトが https://samiii.sharepoint.com だとした場合下記などになります。
| サイトURL | |
|---|---|
| ルート サイト | https://samiii.sharepoint.com |
| Redチームのサイト | https://samiii.sharepoint.com/sites/red |
| Blueチームのサイト | https://samiii.sharepoint.com/teams/blue |
| サブサイト | https://samiii.sharepoint.com/green |
Redチームのサイトは下記のような感じで、メニューの ホーム をクリックして表示される画面のURLがサイトURLです！
2. 対象サイトの管理者権限を付与する
「3. クライアントの登録」 を行う際に、対象サイトの管理者の権限が必要です。
既に対象サイトの管理者の権限が付与されている場合は、skip して OKです。
なお、管理者権限の付与には、Azure AD ロール の SharePoint管理者 が必要です。
Azure AD ロール の画面 から、 SharePoint管理者 のロールを割り当ててもらってください。（ SharePoint管理者 のロールの割り当てには グローバル管理者 であることが必要です）
あるいは、 SharePoint管理者 のロールを持っている人に、以降のサイト管理者権限の付与作業を依頼してください。
2.1. SharePoint Admin Center にアクセスする
SharePoint Admin Center にアクセスします。
SharePointのルートサイトが https://samiii.sharepoint.com である場合、 https://samiii-admin.sharepoint.com が SharePoint Admin Center です。
2.2. 対象のサイトの管理者追加画面を開く
左のメニューの [サイト] > [アクティブなサイト] から、対象のサイトを検索して選択し、上部メニューの [権限] > [その他の管理者の管理] を選択します。
2.3. 対象のサイトの管理者を追加する
管理者の追加画面が表示されるので、管理者権限を付与するユーザを入力&選択して [保存] します。保存が完了したら、管理者権限の付与は完了です。
3. クライアントの登録
OAuth 2.0 のフローでアクセストークンを取得するためには、 client_id と client_secret が必要です。
Microsoftのドキュメントに記載されている「アドインの登録」を行えば発行されますので、登録を行います。
対象サイトの管理者権限がないユーザで操作をしようとすると、「申し訳ございません、アクセス許可がありません。」と記されたエラー画面が表示されます。事前に操作を行うユーザに管理者権限が付与されていることを確認するか、サイト管理者の権限が付与されているユーザで操作を行ってください。
3.1. クライアントの登録（アドインの登録）
AppRegNew.aspx を使用して登録するには を参考に、AppRegNew.aspx を利用して登録します。
ブラウザーで <site collection url>/_layouts/15/AppRegNew.aspx にアクセスしてください。（対象サイトのサイトURLが https://samiii.sharepoint.com/teams/blue だとすると、https://samiii.sharepoint.com/teams/blue/_layouts/15/AppRegNew.aspx にアクセス）
登録画面が表示されるので、各項目に適切な内容を入力し、[作成] ボタンを押下します。
| 項目 | 例 | 説明 |
|---|---|---|
| クライアント ID | epat9p9hdh4m8-ems9j-9ch7-z4tvs49w734 | 「生成」ボタンを押すと自動生成される |
| クライアント シークレット | AhGgcsyHGf44T8QJbTKrvsvjkVhVbQppec8Z5BhzRdBs | 「生成」ボタンを押すと自動生成される |
| タイトル | テストアプリ | トークン取得時の同意画面に表示されるクライアントの名前 |
| アプリ ドメイン | localhost | localhostでも良いし、samiii.co.jp のようなドメインでも良い。https://アプリドメイン でアクセスできるかどうかの確認はしている模様。 |
| リダイレクト先 URL | https://samiii.co.jp/oauth2/redirect_uri | いわゆる redirect_uri ここに code が送付される |
登録が完了すると、「アプリ ID が正常に作成されました。」の文言とともに、登録された各項目の内容が表示されますので、画面の内容を保存しておいてください。
3.2. クライアントが扱うスコープの登録
AppInv.aspx を利用して、スコープ情報を登録します。
ブラウザーで <site collection url>/_layouts/15/AppInv.aspx にアクセスしてください。（対象サイトのサイトURLが https://samiii.sharepoint.com/teams/blue だとすると、https://samiii.sharepoint.com/teams/blue/_layouts/15/AppInv.aspx にアクセス）
下記のような画面が表示されるので、各項目に適切な内容を入力し、[作成] ボタンを押下します。
| 項目 | 例 | 説明 |
|---|---|---|
| アプリ ID | epat9p9hdh4m8-ems9j-9ch7-z4tvs49w734 | 「3.1. クライアントの登録」で登録したクライアント ID |
| タイトル | テストアプリ | アプリ ID を入力した状態で [参照]を押下すると登録されている内容が自動で表示される |
| アプリ ドメイン | localhost | アプリ ID を入力した状態で [参照]を押下すると登録されている内容が自動で表示される |
| リダイレクト先の URL | https://samiii.co.jp/oauth2/redirect_uri | アプリ ID を入力した状態で [参照]を押下すると登録されている内容が自動で表示される |
| 権限の要求 XML | 表外に記載 | スコープの種類等はアドインのアクセス許可とアクセス許可スコープの種類参照 |
<AppPermissionRequests>
<AppPermissionRequest
Scope="http://sharepoint/content/sitecollection/web/list"
Right="Write"/>
</AppPermissionRequests>
「3.1. クライアントの登録（アドインの登録）」で登録した「タイトル」、入力したスコープ情報の説明が表示された確認画面が表示されます。内容に相違なければ、[信頼する]を押下して登録完了です。
3.3. 【参考】 登録したクライアントの削除
「間違えて登録してしまった！！！」
「登録したクライアントの情報 （ID と シークレット) を共有してはいけない人と共有してしまったので、更新したい！」
そんな場合は、 AppPrincipals.aspx を利用して登録済みクライアントの一覧表示および削除が可能です。
ブラウザーで <site collection url>/_layouts/15/AppPrincipals.aspx にアクセスしてください。（対象サイトのサイトURLが https://samiii.sharepoint.com/teams/blue だとすると、https://samiii.sharepoint.com/teams/blue/_layouts/15/AppPrincipals.aspx にアクセス）
対象サイトのクライアントとして登録されたものの一覧が表示されます。削除したいものの横の [×] をクリックすると削除可能です。
3.4. 【参考】 予期しないエラーが発生しました
「3.1. クライアントの登録」 や 「3.2. クライアントが扱うスコープの登録」 で [作成] を押下した後、正常に完了せずに「申し訳ございません。何らかの問題が発生しました。」というタイトル、「予期しないエラーが発生しました。」という詳細情報の何の役にも立たないエラー画面が表示されることがあります。
私の場合は入力した内容が何らかの条件を満たしていない場合にこの画面になりました。
具体的には下記のような感じです。
- 「アプリ ドメイン」に存在しないドメインを入力した
- 「権限の要求 XML」にXML形式でないものを入力した
- 「権限の要求 XML」に解釈できない要素や属性を記載した
参考までに。
クライアントシークレットやアクセストークンなど、ホンモノっぽいランダム文字列を本文中に記載していますが、記事を書く上で便宜上利用したランダム文字列であり、正しく登録等が行われたものではありません。実際はこの値を使っても動きませんので、ご了承ください。
以上で、アクセストークンの取得に必要なクライアントの登録が完了です！！