2014-01-21

SharepointのREST APIのリファレンスが不親切だったので簡潔に(?)書いてみる。

MicrosoftのサービスのSharepointにREST APIで接続しようとリファレンス見たら、全然わからなかったので、簡潔に書いてみます。

ちなみに、Webのリファレンスたどって色々いじって出来た!っていうパターンなので、もしかしたら間違いがあるかもしれないのでご容赦ください。

流れとしては以下になります。

  1. SharepointでREST API用アプリを作成
  2. 作成したアプリに権限を付与する。
  3. 1で作成したアプリのclient_idとclient_secretでOAuth認証を使ってaccess_tokenを取得。
  4. access_tokenを使ってREST APIをコールする。

1. SharepointでREST API用アプリを作成する。

https://<site url>/_layouts/15/appregnew.aspx にアクセスし、アプリ情報を入力を、作成ボタンを押下する。

appregnew

ここで入力したアプリドメインやリダイレクトURLは一度決定すると、Sharepointサイトで編集できないっぽいので注意。(もしかしたら、CLIとかでは編集できるのかもしれないけど未調査)

ちなみにsite urlはサブサイトの場合は https://hoge.sharepoint.com/sites/{sub}/_layouts/15/appregnew.aspx というURLになるので注意(サブディレクトリを含むURLになる)

2. 作成したアプリに権限を付与する。

https://<site url>/_layouts/15/appinv.aspx にアクセスし、1で生成したアプリのアプリID(クライアントID)を入力し、参照ボタンを押下すると先ほど作成したアプリの内容が表示されます。

appinv

ここで権限要求のXMLに権限に関する情報を入力します。

フルコントロールであれば以下の様な感じ。

<AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />
</AppPermissionRequests>

権限の要求範囲URLとかはここを参照。

入力後は作成ボタンを押下して、設定を反映します。

設定反映後は https://<site url>/_layouts/15/appprincipals.aspx にアクセスし、作成したアプリが表示されていることを確認する。

appprincipals

1でアプリを作成した時点ではこの一覧には表示されないっぽいです。

3. OAuthを使ってaccess_tokenを取得

https://<site url>/_layouts/15/OAuthAuthorize.aspx?client_id=<client_id> &scope=<scope>&response_type=code&redirect_uri=<redirect_uri> にブラウザからGETリクエストを送信します。

すでにSharepointにログインしている状態であれば認可画面が出るので、「信頼する」ボタンを押下します。以下はIsDlg=1のURLパラメータを付与しており、ダイアログボックス用のレイアウトになっています。

oauth

「信頼する」ボタンを押下すると設定したredirect_uriにURLパラメータ「code」に値が入力された状態でリダイレクトします。アプリ側でこのcodeの値を使って以下のパラメータをBodyに格納して https://accounts.accesscontrol.windows.net/<office365 realm>/tokens/OAuth/2 に対してPOSTします。

'grant_type' => 'authorization_code',
'client_id' => <client_id> + '@' + <office365 realm>,
'client_secret' => <client_secret>,
'code' => <取得したcode>,
'redirect_uri' => <redirect_uri>,
'resource' => '00000003-0000-0ff1-ce00-000000000000/' + <sharepoint realm>+ '@' + <office365 realm>

ここらへんはOAuth2.0のフローと同じでPOSTするとresponseとしてaccess_tokenやらrefresh_tokenが返されます。詳細はこちら

4. access_tokenを使ってREST APIをコールする。

3でaccess_tokenを取得できるので、リクエストのHttpヘッダに"Authorization: Bearer "を入れて各REST APIを呼び出せばOKです。

Acceptヘッダを特に入力しないとXML形式、Acceptヘッダに"application/json; odata=verbose"を入力するとodata形式(JSON)でレスポンスが返ってきます。

access_tokenの期限が切れたらrefresh_tokenでaccess_tokenを再取得すればOK。

その場合はエンドポイントは同じで https://accounts.accesscontrol.windows.net/<office365 realm>/tokens/OAuth/2 に対して

grant_type' => 'refresh_token',
'client_id' => <client_id>+ '@' + <office365 realm>,
'client_secret' => <client_secret>,
'refresh_token' => <refresh_token>,
'resource' => '00000003-0000-0ff1-ce00-000000000000/' + <sharepoint realm> + '@' + <office365 realm>

をPOSTしてあげればOK。

サンプルのapexクラスに関しては次回!

このエントリーをはてなブックマークに追加