Uncategorized

OneDrive API を使ったアプリケーション開発

By on • ( 7 Comments )

Office 365 API
(※ 現在、統一エンドポイントとして Microsoft Graph がご利用いただけます)

(Skype API は こちら)

OneDrive を使用した新規開発については、今後は Microsoft Graph をご利用ください。
Microsoft Graph では、Azure AD v2 endpoint を使用した認証や、「最近使ったファイル」 (/drive/recent)、「検索」 (/drive/root/search(q='{url encoded search string}’)) なども可能です。下記 Uri を使用します。
/users/{id}/drive/items/{id}/children
(/users/{id}/drive/root/children 含む)

こんにちは。

ご存じの方も多いかと思いますが、OneDrive には REST API (OneDrive API) が提供されています。
今回は、この API (OneDrive API) について簡単に紹介します。

アプリケーション構築のおおまかな流れは以下の通りです。

  1. OAuth 2.0 の処理をおこないます。(Microsoft Account または Azure AD)
  2. 受け取った access token を使って、OneDrive API を呼び出します。

補足 : OneDrive for Business API では「Azure AD : Backend Server-Side アプリの開発 (Deamon, Service など)」で紹介した証明書を使用した方式も扱えます。

アプリ登録

まず、アイデンティティ基盤にアプリケーション登録をおこなって、API 呼び出しの際に必要になる client id (app id), client secret (app secret) などを取得します。

Azure Portal (https://portal.azure.com/) に Office 365 の管理者アカウントでログインをおこなって、Azure AD の管理画面でアプリケーションを登録します。(設定手順詳細は「Office 365 API 入門」を参照してください。)
アプリケーションの種類として、[Accounts in any organizational directory (Any Azure AD directory – Multitenant) and personal Microsoft accounts] を選択します。

OneDrive (一般) を使用する場合、登録したアプリケーションの [Authentication] (認証) メニューを選択して、[Live SDK support] が [Yes] (はい) になっていることを確認してください。

また、OneDrive for Business / SharePoint Online を使用する場合は、[API Permissions] メニューを選択して、下図の [SharePoint Online] の Permission (アクセス許可) を設定してください。

Access Token の取得

OAuth 2.0 の Flow で access token を取得します。

OneDrive の場合

Microsoft Account の OAuth 2.0 を使った認証とアクセス トークン (access token) の取得までの流れについては、「Live Services (Outlook.com, OneDrive, etc) 開発」に流れを記載しましたので参照してください。(ここでは解説を省略します。)

Scope として ondrive.readonly (読み込みのみの場合) か onedrive.readwrite (書き込みをおこなう場合) を必ず含めてください。(なお、Scope を複数指定するには、wl.signin%20onedrive.readwrite のように指定します。)

OneDrive for Business / SharePoint Online の場合

Azure AD の OAuth 2.0 を使った認証とアクセス トークン (access token) の取得までの流れについては、「Office 365 API 入門」に流れを記載しましたので参照してください。(ここでは解説を省略します。)

Resource name には https://{tenant prefix}-my.sharepoint.com/ (SharePoint Online の場合は https://{tenant}.sharepoint.com) を指定してください。

OneDrive API (REST API) の呼び出し

アクセス トークン (Access Token) が取得できたら、あとは、REST API を呼び出すだけです。

例えば、ルート直下のサブ フォルダー一覧 (OneDrive のフォルダー一覧) を取得する場合は、以下の通り呼び出します。
下記で、api-version には「v1.0」などの API のバージョンの値、access token には、上記で取得したアクセス トークンの値です。(OneDrive 側も Authorization ヘッダーに入れることができます。)

今回は直下のフォルダ/ファイルを全件取得していますが、OData を使った Filter (クエリ―) も可能です。

OneDrive (Microsoft Account) の場合

GET https://api.onedrive.com/{api-version}/drive/root/childrenAuthorization: BEARER {access token}

OneDrive for Business (Azure AD) の場合

https://{tenant prefix}-my.sharepoint.com/_api/{api-version}/drive/root/childrenAuthorization: BEARER {access token}

補足 : SharePoint Online の場合は、https://{tenant}.sharepoint.com/{site-relative-path}/_api/v2.0 を使用します。

補足 : OneDrive (Microsoft Account) の場合は、https://api.onedrive.com/{api-version}/drive/root/children?access_token={access token} としても構いません。(セキュリティ上、あまりおすすめの方法ではありませんが。)

なお、結果は、下記の通り Json で返ってきます。(下記は OneDrive の場合のサンプルです。)
なお、アイテムが File の場合には、下記の folder : { } が file : { } になります。

{  "value": [{  "createdBy": {"application": {  "displayName": "OneDrive website",  "id": "44048800"},"user": {  "displayName": "Tsuyoshi Matsuzaki",  "id": "9c0af81b735e29ea"}  },  "createdDateTime": "2014-09-16T05:28:55.977Z",  "cTag": "aZjo5QzBBRjgxQjczNUUyOUVBIT...",  "eTag": "aOUMwQUY4MUI3MzVFMjlFQSE1NT...",  "id": "9C0AF81B735E29EA!5518",  "lastModifiedBy": {"application": {  "displayName": "OneDrive website",  "id": "44048800"},"user": {  "displayName": "Tsuyoshi Matsuzaki",  "id": "9c0af81b735e29ea"}  },  "lastModifiedDateTime": "2014-12-19T07:06:27.39Z",  "name": "My travel 2015",  "parentReference": {"driveId": "9c0af81b735e29ea","id": "9C0AF81B735E29EA!112","path": "/drive/root:"  },  "size": 13362755,  "webUrl": "https://onedrive.live.com/redir?page=self&resid=9C0AF81B735E29EA!5518",  "folder": {"childCount": 4  }},{  "createdBy": {"application": {  "displayName": "OneDrive website",  "id": "44048800"},"user": {  "displayName": "Tsuyoshi Matsuzaki",  "id": "9c0af81b735e29ea"}  },  "createdDateTime": "2014-10-01T06:53:05.333Z",  "cTag": "aZjo5QzBBRjgxQjczNUUyOUVBIT...",  "eTag": "aOUMwQUY4MUI3MzVFMjlFQSE1Nj...",  "id": "9C0AF81B735E29EA!5681",  "lastModifiedBy": {"application": {  "displayName": "OneDrive website",  "id": "44048800"},"user": {  "displayName": "Tsuyoshi Matsuzaki",  "id": "9c0af81b735e29ea"}  },  "lastModifiedDateTime": "2015-02-18T13:39:45.7Z",  "name": "Photo of my son",  "parentReference": {"driveId": "9c0af81b735e29ea","id": "9C0AF81B735E29EA!112","path": "/drive/root:"  },  "size": 10532172,  "webUrl": "https://onedrive.live.com/redir?page=self&resid=9C0AF81B735E29EA!5681",  "folder": {"childCount": 3  }},. . .  ]}

上記の 9C0AF81B735E29EA!5518 の ID のフォルダー内のファイル (またはサブ フォルダ) を取得するには、下記の通り呼び出します。

OneDrive (Microsoft Account) の場合

GET https://api.onedrive.com/{api-version}/drive/items/9C0AF81B735E29EA!5518/childrenAuthorization: BEARER {access token}

OneDrive for Business (Azure AD) の場合

https://{tenant prefix}-my.sharepoint.com/_api/{api-version}/drive/items/9C0AF81B735E29EA!5518/childrenAuthorization: BEARER {access token}

また、以下は、ファイルを「hello.docx」という名前で登録 (アップロード) します。

同様に、9C0AF81B735E29EA!5518 は登録先のアイテム (フォルダー) の ID で、上記で取得した id の値です。(また、保存するファイルの種類に応じて Content-Type を設定してください。下記の例では、Word 文書をアップロードしています。)

OneDrive の場合

POST https://api.onedrive.com/{api-version}/drive/items/9C0AF81B735E29EA!5518/childrenContent-Type: multipart/related; boundary=A300testxAuthorization: BEARER {Access Token Value} --A300testxContent-ID: <metadata>Content-Type: application/json{  "name": "hello.docx",  "file": {},  "@content.sourceUrl": "cid:content",  "@name.conflictBehavior": "rename"}--A300testxContent-ID: <content>Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document{Word 文書のストリーム、または、そのエンコード文字列 . . .}--A300testx--

OneDrive for Business の場合

POST https://o365directory-my.sharepoint.com/_api/{api-version}/drive/items/01B6UXIPO64QDEZHFYPBFIJCX4YYIYAQPW/childrenContent-Type: multipart/related; boundary=A300testxAuthorization: BEARER {Access Token Value} --A300testxContent-ID: <metadata>Content-Type: application/json{  "name": "hello.docx",  "file": {},  "@content.sourceUrl": "cid:content",  "@name.conflictBehavior": "rename"}--A300testxContent-ID: <content>Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document{Word 文書のストリーム、または、そのエンコード文字列 . . .}--A300testx--

注意 : と書きましたが、現時点 (2015/12) の OneDrive for Business では、まだ Mutipart の upload には対応できていないようです。OneDrive for Business の場合は、OneDrive API Document に記載されている他の方法 (Multipart 以外) を使って Upload してください。

上記は単純な読み書きのサンプルですが、新 OneDrive API を使用すると、(ビデオ ファイルなど大容量ファイルの) ファイル分割によるダウンロードやアップロード、変更点のみを取得して処理する同期ソリューションの開発、OData を使用したクエリなども可能です。(2015/02/26 追記)

OneDrive API で可能なこと

OneDrive API では、ファイルの読み書き以外に、以下のような高度な操作も可能です。

  • ファイルの共有 (Share) とリンクの取得
  • Large file (ただし、10 GB までのファイル) の分割アップロード
  • 通知 (Webhook) と差分更新によるファイル同期 (Synchronization)。
    「OneDrive API を使った通知 (Webhook) と同期 (Synchronization)」を参照してください。
  • OneDrive (OneDrive for Business と OneDrive 双方) のファイル選択をおこなう際、File Picker を独自に実装する方法以外に、OneDrive File Picker SDK を使用する方法もあります。現在、JavaScript 版と Android 版があります。

 

この OneDrive API を使用した Web アプリケーション (ASP.NET MVC) のサンプルを下記に作成しましたので、細かなプログラミング方法などはソース コードをご参照ください。C# のサンプル コードですが、もちろん、.NET 以外の開発言語からでも簡単に実装できます。(Json の Parse の箇所は、開発言語にあわせて適した方法で実装してください。)

デモ サイト :
http://cloudstoragesample.azurewebsites.net/

ソース コードの Download (OneDrive) :
https://1drv.ms/u/s!AuopXnMb-Aqcge1gvx4o5wtKuhJAhQ?e=2411Pf

このサンプル アプリケーションの使い方は、「Office & Office 365 Development Sample」 に追記しました。
このサンプルでは、OpenXML SDK で作成した Word 文書を OneDrive に保存しています。(Json の処理では、DataContractJsonSerializer を使用しています。) Word 2007 以上を持っていないユーザーでも、OneDrive の Office Online で (ブラウザーを使って) 閲覧できます。

補足 : Access Token は、1 時間ほどで期限切れ (Expire) になります。このダウンロード サンプルでは省略していますが、Access Token が期限切れになった場合は、再度、同じステップで Access Token を取得しなおしてください。(利用者が同一ブラウザーを使用している場合、Windows Live ID が設定する Cookie が残っているため、ユーザー ID / パスワードの入力画面は表示されずに Accss Token を取得できます。)
また、利用者がアプリを閉じた後でも、Refresh Token と呼ばれるものを保持し、これを使って Access Token を取得しなおすことで処理を継続できます。(上記のダウンロード サンプルに、コメントとして記載しています。) OneDrive で Refresh Token を取得するには、OAuth Flow における最初の Authentication Code の取得の際 (ログインの際) に、scope として wl.offline_access を追加します。(このシナリオは、Mobile Application の場合などに使用できます。)

 

※ 変更履歴

2015/02/26  New OneDrive API の内容を反映 (https://apis.live.net/v5.0/me/skydrive -> https://api.onedrive.com/v1.0/)

2015/12/22  v2.0 の記述を追加

2016/03/31  SharePoint Online も対応したため、記述を追加

2016/04/21  https://account.live.com/developers/applications/ から https://apps.dev.microsoft.com/ に変更

2016/05/30  新 Azure Portal (https://portal.azure.com) に画面を変更

Categories: Uncategorized

Tagged as:

7 replies»

  1. Pingback: OneDrive API を使った通知 (Webhook) と同期 (Synchronization) – tsmatz
  2. Pingback: Office & Office 365 Development Sample (Cloud 開発サンプル) – tsmatz
  3. Pingback: Live Services (Outlook.com, OneDrive, etc) 開発 – tsmatz
  4. Pingback: ASP.NET MVC で OpenID、OAuth とバリバリ連携 (DotNetOpenAuth) | @Subaru
  5. Pingback: Excel のクラウドな開発 (OneDrive 編) – tsmatz
  6. Pingback: Azure ACS の Custom ID Provider の作成 : OpenID 編 – tsmatz
  7. Pingback: Windows Azure の ACS で認証トークン (FedAuth Cookie など) が Expire (期限切れ) になった場合の対処 – tsmatz

Leave a Reply