Microsoft Graph での OneDrive と SharePoint

OneDrive REST API は Microsoft Graph API の一部で、アプリが OneDrive と SharePoint に保存されているコンテンツに接続できるようにします。 REST API は OneDrive、OneDrive for Business、SharePoint ドキュメント ライブラリ、およびオフィス グループ間で共有され、アプリは同じコードを使用してこれらの場所にあるコンテンツを柔軟に読み取ったり、保存したりできます。

REST API は、Microsoft のサービスで使用される共通の API である Microsoft Graph の一部です。

Microsoft Graph 以外で OneDrive API を利用している既存のソリューション、または SharePoint Server 2016 をターゲットとするソリューションの場合、このドキュメントを読み進める上で必要な背景情報については、直接エンドポイントの相違点を参照してください。

はじめに

Microsoft Graph とファイル アクセスを手軽に試してみるには、Graph エクスプローラーと Microsoft Graph クイック スタートをご利用ください。

OneDrive の REST API では、API でアドレス指定可能なリソースを表現する、以下のいくつかの最上位タイプが提供されています。

• drive(最上位オブジェクト)
• driveItem(ファイルとフォルダー)

次に、driveItem リソースの例を示します。

{
  "@microsoft.graph.downloadUrl":"http://public-sn3302.files.1drv.com/y2pcT7OaUEExF7EHOl",
  "createdDateTime": "2014-10-31T03:37:04.72Z",
  "eTag": "aRDQ2NDhGMDZDOTFEOUQzRCE1NDkyNy4w",
  "id":"D4648F06C91D9D3D!54927",
  "lastModifiedBy": {
    "user": {
      "displayName": "daron spektor",
      "id": "d4648f06c91d9d3d"
    }
  },
  "name":"BritishShorthair.docx",
  "size":35212,
  "file": {
    "hashes":{
      "sha1Hash":"cf23df2207d99a74fbe169e3eba035e633b65d94"
    }
  }
}

リソースに関するデータは、以下の 3 つの方法で提供されます。

• プロパティ (id や name など) は単純な値を公開します。
• ファセット (file や photo など) は複雑な値を公開します。 アイテムのファセットが存在する場合は、通例、アイテムの動作または能力と、関連するプロパティを示しています。
• 参照 (children など) はその他のリソースのコレクションを指します。

多くの要求について、追加のデータを含めたり、使用しないプロパティを応答から削除したりする調整ができます。 OneDrive では、オプションのクエリ パラメーターを使用して、この機能が実現されています。 どのパラメーターがサポートされるかについては、このドキュメント全体を通じて、要求ごとに詳細なコンテキストを示します。

既定では、プロパティとファセットはほとんどが返されるのに対し、参照はいずれも表示されません。 効率を高めるには、注目すべきデータに select と expand を指定することをお勧めします。

リソースとファセットの詳細については、「リソース」と「ファセット」を参照してください。

Microsoft Graph のルート リソース

Microsoft Graph では、いくつかのルート リソースから OneDrive の機能を使用できます。 これらのリソースは、OneDrive ドキュメント ライブラリと SharePoint ドキュメント ライブラリを使用できる Office 365 内の場所に対応しています。 Microsoft Graph の以下のエンティティは、ドライブを 1 つまたはそれ以上含んでいる場合があります。

エンティティ	パスの例
ユーザー	/v1.0/users/{id} または /v1.0/me
グループ	/v1.0/groups/{id}
サイト	/v1.0/sites/{id}

OneDrive のルート リソース

Microsoft Graph のルート リソースをアドレス指定するときは、アプリで以下のパスを使用して OneDrive のリソースをアドレス指定できます。

パス	リソース
/drives	認証されたユーザーが使用できる drive リソースを一覧表示する。
/drives/{drive-id}	ドライブの ID を使用して特定の drive にアクセスする。
/drives/{drive-id}/root/children	特定の drive のルートにあるアイテムを一覧表示する。
/drive/items/{item-id}	ID を使用して driveItem にアクセスする。
/drive/special/{special-id}	既知の名前を使用して既知のフォルダーにアクセスする。
/shares/{share-id}	shareId または共有用 URL を使用して driveItem にアクセスする。

ドライブ内でのパス ベースのアドレス指定

driveItem は、一意識別子でアドレス指定することも、ドライブ階層でのアイテムの位置 ( ユーザー パス) でアドレス指定することもできます。 API 要求の中でコロン (:) を使用すると、API パス空間とユーザー パス空間を切り替えることができます。 この構文は、API 空間を通じてアドレス指定される、どの driveItem にも適用できます。

ファイル システム パス空間の末尾でコロンを使用して、もう一度 API パス空間に切り替えることもできます。 URL に含まれているユーザー データが、アドレス指定とパス エンコードの要件に従っていることをご確認ください。

パス	リソース
/drive/root:/path/to/file	ルート以下のパスを使用して driveItem にアクセスする。
/drive/items/{item-id}:/path/to/file	別のアイテムからの相対パスを使用して driveItem にアクセスする。
/drive/root:/path/to/folder:/children	ドライブ ルートからの相対パスを使用してアクセスするとき、子を一覧表示する。
/drive/items/{item-id}:/path/to/folder:/children	別のアイテムからの相対パスを使用してアクセスするとき、子を一覧表示する。

共有フォルダーおよびリモート アイテム

個人用の OneDrive を利用しているユーザーは、別のドライブから自分の OneDrive に 1 つ以上の共有アイテムを追加できます。 これらの共有のアイテムは、remoteItem ファセットを持つ children コレクションの driveItem として表示されます。

さらに、ターゲット ドライブ以外からアイテムが返される状況の場合も、remoteItem ファセットが含まれています。 これらのアイテムは、検索、最近使用したファイル、共有アイテムから返される場合もあります。

共有フォルダーとリモート アイテムの操作方法の詳細については、「リモート アイテムおよび共有フォルダー」を参照してください。

共有とアクセス許可

OneDrive と SharePoint での最も一般的な操作の 1 つは、他のユーザーとアイテムを共有することです。 OneDrive を使用することによって、ドライブ内に保存されているアイテムについて、アプリで共有リンクを作成することや、アクセス許可を追加して、招待状を送信することができます。

また、アプリで共有リンクから直接共有コンテンツにアクセスすることも可能になります。

共有コンテンツを共有および使用する方法の詳細については、「OneDrive 内のアイテムの共有」を参照してください。

Webhook と通知

OneDrive では、OneDrive 内のコンテンツが変更されたときに webhook スタイルのプッシュ通知を送信できます。 これらの通知をアプリで利用すると、サーバーをポーリングして変更の有無を確認するのではなく、ほぼリアルタイムで変更をトラックできます。

プログラミング上の注意点

API の互換性

OneDrive は継続的に開発が進められ、機能が拡充されています。 API のパスには、重大な変更からアプリを保護することを目的として、バージョン番号が含まれています。 重大な変更が必須となる場合は、API のバージョン番号が増加します。 変更前のバージョン番号の API を呼び出す既存のアプリは、当該の変更によって影響を受けることはありません。 あるバージョンの API がサポートされる期間については、Microsoft Graph のサポート ポリシーを参照してください。

重大な変更とは、要求または応答の形式において、文書化されている既存の動作を廃止または変更するか、リソースの定義から要素を削除する変更です。 操作、プロパティ、ファセット、参照をリソースに追加するものは、重大な変更ではありません。

API については、随時、文書化されていない追加の機能が公開される可能性があります。 これらの機能は、文書化されるまで利用しないでください。 現行の動作は、ドキュメントの記述とは異なっている場合、将来も存続するとは限りません。

Microsoft は、API の既存のバージョンに対して、ファセット、プロパティ、リソースを API に追加することを含め、重大ではない変更を継続的に導入しています。 したがって、API を呼び出すコードについては、以下を遵守することが必要です。

• JSON 応答に新たに追加されていくプロパティに対して、弾力的に対応する。 それらのプロパティを無視することは問題ありません。
• JSON 応答で返されるプロパティの順序に依存しない。
• 文書化されている API パス、リソース、プロパティ、列挙値のみを使用する。 文書化されていない値は、変更されない保証はありません。
• OneDrive API から返される URL は、すべてあいまいな URL として扱う。 アプリでは、これらの URL の形式またはパラメーターのどの部分も前提としないでください。 この URL は将来予告なしに変更されることがあります。

調整

OneDrive では、ユーザーやアプリが他のユーザーのエクスペリエンスに悪影響を及ぼすことがないよう、使用上限が導入されています。 あるアクティビティで OneDrive の使用上限を超過した場合は、しばらくの間、API 要求が拒否されます。 OneDrive から、アプリで要求を再び送信できるようになるまでの待機秒数が記述された Retry-After ヘッダーが返される場合もあります。

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

OneNote ノートブックの操作

注:OneDrive で OneNote のノートブックを保存することはできますが、OneNote のノートブックを OneDrive API を使用して操作しないでください。 代わりに、OneNote API を使用します。

ドキュメントの継続的検証

Microsoft は、ドキュメントの質を高める取り組みの一環として、ドキュメントに記載されているサンプルおよび事例の妥当性を、チェックインのたびに検証する手順を導入しています。 Microsoft では、この取り組みをドキュメントの継続的検証と呼んでいます。

ドキュメントに変更を加える際は、その都度、サービスのすべてが文書化されたとおりに動作するかどうかが検証されます。 サービスの新しいビルドを作成するにあたっては、ドキュメント内の例を引き続き適用できるかどうかが検証されます。 この取り組みは、文書化したすべての対象が適切に機能すること、新しい更新プログラムが利用可能となった後も想定どおりに機能することを保証する上で役立っています。

最新のビルドの詳細については、Microsoft のドキュメント リポジトリに関する AppVeyor のビルドの状態ページを参照してください。

関連項目

以下のトピックで、OneDrive API に当てはまるその他のコンセプトの概要を紹介しています。

• リソースのアドレス指定
• 認証とサインイン
• 大文字と小文字の区別
• エラー応答
• HTTP 動詞のトンネリング
• Live Connect と Live SDK からの移行
• 使用条件