Microsoft Graph での OneDrive と SharePointOneDrive and SharePoint in Microsoft Graph

ドキュメントの検証とビルドの状態Documentation validation and build status

OneDrive REST API は Microsoft Graph API の一部で、アプリが OneDrive と SharePoint に保存されているコンテンツに接続できるようにします。The OneDrive REST API is a portion of the Microsoft Graph API which allows your app to connect to content stored in OneDrive and SharePoint. REST API は OneDrive、OneDrive for Business、SharePoint ドキュメント ライブラリ、およびオフィス グループ間で共有され、アプリは同じコードを使用してこれらの場所にあるコンテンツを柔軟に読み取ったり、保存したりできます。The REST API is shared between OneDrive, OneDrive for Business, SharePoint document libraries, and Office Groups, to allow your app the flexibility to read and store content in any of these locations with the same code.

REST API は、Microsoft のサービスで使用される共通の API である Microsoft Graph の一部です。These REST APIs are a part of the Microsoft Graph, a common API for Microsoft services.

Microsoft Graph 以外で OneDrive API を利用している既存のソリューション、または SharePoint Server 2016 をターゲットとするソリューションの場合、このドキュメントを読み進める上で必要な背景情報については、直接エンドポイントの相違点を参照してください。For existing solutions using OneDrive API outside of Microsoft Graph, or solutions targeting SharePoint Server 2016, see direct endpoint differences for more context on reading this documentation.

はじめにGetting started

Microsoft Graph とファイル アクセスを手軽に試してみるには、Graph エクスプローラーMicrosoft Graph クイック スタートをご利用ください。To quickly experiment with Microsoft Graph and accessing files, check out the Graph Explorer and the Microsoft Graph Quick Start.

OneDrive の REST API では、API でアドレス指定可能なリソースを表現する、以下のいくつかの最上位タイプが提供されています。OneDrive's REST API provides a few top-level types that represent addressable resources in the API:

次に、driveItem リソースの例を示します。The following is an example of a driveItem resource.

{
  "@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 つの方法で提供されます。Data about a resource is provided in three ways:

  • プロパティ (idname など) は単純な値を公開します。Properties (like id and name) expose simple values.
  • ファセット (filephoto など) は複雑な値を公開します。Facets (like file and photo) expose complex values. アイテムのファセットが存在する場合は、通例、アイテムの動作または能力と、関連するプロパティを示しています。The presence of facets on an item generally indicate behaviors or capabilities of an item and related properties.
  • 参照 (children など) はその他のリソースのコレクションを指します。References (like children) point to collections of other resources.

多くの要求について、追加のデータを含めたり、使用しないプロパティを応答から削除したりする調整ができます。Many requests can be tailored to include additional data or remove unused properties from the responses. OneDrive では、オプションのクエリ パラメーターを使用して、この機能が実現されています。OneDrive uses optional query parameters to enable this functionality. どのパラメーターがサポートされるかについては、このドキュメント全体を通じて、要求ごとに詳細なコンテキストを示します。Throughout the documentation, each request provides more context about which parameters are supported.

既定では、プロパティとファセットはほとんどが返されるのに対し、参照はいずれも表示されません。By default, most properties and facets are returned while all references are hidden. 効率を高めるには、注目すべきデータに selectexpand を指定することをお勧めします。For efficiency, we recommend that you specify select and expand for the data you care about.

リソースとファセットの詳細については、「リソース」と「ファセット」を参照してください。For details about resources and facets, see Resources and Facets.

Microsoft Graph のルート リソースMicrosoft Graph root resources

Microsoft Graph では、いくつかのルート リソースから OneDrive の機能を使用できます。Within the Microsoft Graph, the OneDrive functionality is available from several root resources. これらのリソースは、OneDrive ドキュメント ライブラリと SharePoint ドキュメント ライブラリを使用できる Office 365 内の場所に対応しています。These resources correspond to where OneDrive and SharePoint document libraries are available within Office 365. Microsoft Graph の以下のエンティティは、ドライブを 1 つまたはそれ以上含んでいる場合があります。The follow entities in Microsoft Graph may contain one or more drives:

エンティティEntity パスの例Example Path
UserUser /v1.0/users/{id} または /v1.0/me/v1.0/users/{id} or /v1.0/me
GroupGroup /v1.0/groups/{id}
SiteSite /v1.0/sites/{id}

OneDrive のルート リソースOneDrive root resources

Microsoft Graph のルート リソースをアドレス指定するときは、アプリで以下のパスを使用して OneDrive のリソースをアドレス指定できます。When addressing a Microsoft Graph root resource, your app can address OneDrive resources using the following paths:

パスPath リソースResource
/drives 認証されたユーザーが使用できる drive リソースを一覧表示する。List drive resources available to the authenticated user.
/drives/{drive-id} ドライブの ID を使用して特定の drive にアクセスする。Access a specific drive by its ID.
/drives/{drive-id}/root/children 特定の drive のルートにあるアイテムを一覧表示する。List items in the root of a specific drive.
/drive/items/{item-id} ID を使用して driveItem にアクセスする。Access a driveItem by its ID.
/drive/special/{special-id} 既知の名前を使用して既知のフォルダーにアクセスする。Access a known folder by its known name.
/shares/{share-id} shareId または共有 URL を使用して driveItem にアクセスする。Access a driveItem by its shareId or a sharing URL.

ドライブ内でのパス ベースのアドレス指定Path-based addressing within a drive

driveItem は、一意識別子でアドレス指定することも、ドライブ階層でのアイテムの位置 (ユーザー パス) でアドレス指定することもできます。A driveItem can be addressed by either a unique identifier or where that item exists in the drive's hierarchy (i.e. user path). API 要求の中でコロン (:) を使用すると、API パス空間ユーザー パス空間を切り替えることができます。Within an API request, a colon can be used to shift between API path space and user path space. この構文は、API 空間を通じてアドレス指定される、どの driveItem にも適用できます。This syntax is valid for any driveItem addressed via the API space.

ファイル システム パス空間の末尾でコロンを使用して、もう一度 API パス空間に切り替えることもできます。You can also transition back to API path space by using a colon at the end of the file system path space. URL に含まれているユーザー データが、アドレス指定とパス エンコードの要件に従っていることをご確認ください。Ensure user data within the URL follows the addressing and path encoding requirements.

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

共有フォルダーおよびリモート アイテムShared folders and remote items

個人用の OneDrive を利用しているユーザーは、別のドライブから自分の OneDrive に 1 つ以上の共有アイテムを追加できます。これらの共有のアイテムは、remoteItem ファセットを持つ children コレクションの driveItem として表示されます。OneDrive personal allows a user to add one or more shared items from another drive to their OneDrive. These shared items appear as a driveItem in the children collection with a remoteItem facet.

さらに、ターゲット ドライブ以外からアイテムが返される状況の場合も、remoteItem ファセットが含まれています。In addition, scenarios where items are returned from outside the target drive will also include a remoteItem facet. これらのアイテムは、検索最近使用したファイル共有アイテムから返される場合もあります。These items may also be returned from search, recent files, shared with me.

共有フォルダーとリモート アイテムの操作方法の詳細については、「リモート アイテムおよび共有フォルダー」を参照してください。For more information on working with shared folders and remote items, see Remote items and shared folders.

共有とアクセス許可Sharing and permissions

OneDrive と SharePoint での最も一般的な操作の 1 つは、他のユーザーとアイテムを共有することです。OneDrive を使用することによって、ドライブ内に保存されているアイテムについて、アプリで共有リンクを作成することや、アクセス許可を追加して、招待状を送信することができます。One of the most common actions for OneDrive and SharePoint is sharing items with other people. OneDrive allows your app to create sharing links, add permissions, and send invitations to items stored in a drive.

また、アプリで共有リンクから直接共有コンテンツにアクセスすることも可能になります。OneDrive also provides a way for your app to access shared content directly from the sharing link.

共有コンテンツを共有および使用する方法の詳細については、「OneDrive 内のアイテムの共有」を参照してください。For more details on how to share and consume shared content, see Sharing items in OneDrive.

webhook と通知Webhooks and notifications

OneDrive では、OneDrive 内のコンテンツが変更されたときに webhook スタイルのプッシュ通知を送信できます。OneDrive supports sending webhook-style push notifications when the contents of a OneDrive is changed. これらの通知をアプリで利用すると、サーバーをポーリングして変更の有無を確認するのではなく、ほぼリアルタイムで変更をトラックできます。Your app can use these notifications to track changes in near real-time instead of polling the server for changes.

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

API の互換性API Compatibility

OneDrive は継続的に開発が進められ、機能が拡充されています。OneDrive will continue to evolve and gain additional functionality. API のパスには、重大な変更からアプリを保護することを目的として、バージョン番号が含まれています。The API path includes a version number to protect your app against breaking changes. 重大な変更が必須となる場合は、API のバージョン番号が増加します。When a breaking change is required, the API version number will be incremented. 変更前のバージョン番号の API を呼び出す既存のアプリは、当該の変更によって影響を受けることはありません。Existing apps calling the original version number will remain unaffected by the change. あるバージョンの API がサポートされる期間については、Microsoft Graph のサポート ポリシーを参照してください。See the Microsoft Graph support policy for information about how long a version of the API is supported.

重大な変更とは、要求または応答の形式において、文書化されている_既存の動作を廃止または変更するか、リソースの定義から要素を削除する変更です。A breaking change is a change in the format of a request or response that removes or alters an existing _documented behavior or removes an element of a resource's definition. 操作、プロパティ、ファセット、参照をリソースに追加するものは、重大な変更ではありません。It is not a breaking change to add additional actions, properties, facets, or references to a resource.

API については、随時、文書化されていない追加の機能が公開される可能性があります。It is possible that the API will expose additional undocumented features from time to time. これらの機能は、文書化されるまで利用しないでください。These features should not be utilized until they are documented. 現行の動作は、ドキュメントの記述とは異なっている場合、将来も存続するとは限りません。Do not assume that current behavior that deviates from the documentation will persist.

Microsoft は、API の既存のバージョンに対して、ファセット、プロパティ、リソースを API に追加することを含め、重大ではない変更を継続的に導入しています。We will continue to make non-breaking changes to the existing version of the API, including adding facets, properties, and resources to the API. したがって、API を呼び出すコードについては、以下を遵守することが必要です。As such, any code calling the API needs to:

  • JSON 応答に新たに追加されていくプロパティに対して、弾力的に対応する。Be resilient to additional properties being added to JSON responses. それらのプロパティを無視することは問題ありません。Ignoring them is OK.
  • JSON 応答で返されるプロパティの順序に依存しない。Have no dependency on the order of properties returned in JSON responses.
  • 文書化されている API パス、リソース、プロパティ、列挙値のみを使用する。Use documented API paths, resources, properties, and enumerated values only. 文書化されていない値は、変更されない保証はありません。Non-documented values are not guaranteed to remain consistent.
  • OneDrive API から返される URL は、すべてあいまいな URL として扱う。All URLs returned by OneDrive API should be treated as opaque URLs. アプリでは、これらの URL の形式またはパラメーターのどの部分も前提としないでください。Your app should not make any assumptions about format or parameters in these URLs. この URL は将来予告なしに変更されることがあります。They are subject to change without notice.

調整Throttling

OneDrive では、ユーザーやアプリが他のユーザーのエクスペリエンスに悪影響を及ぼすことがないよう、使用上限が導入されています。OneDrive has limits in place to make sure that individuals and apps do not adversely affect the experience of other users. あるアクティビティで OneDrive の使用上限を超過した場合は、しばらくの間、API 要求が拒否されます。When an activity exceeds OneDrive's limits, API requests will be rejected for a period of time. OneDrive から、アプリで要求を再び送信できるようになるまでの待機秒数が記述された Retry-After ヘッダーが返される場合もあります。OneDrive may also return a Retry-After header with the number of seconds your app should wait before sending more requests.

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

OneNote のノートブックの操作Working with OneNote Notebooks

注: OneDrive で OneNote のノートブックを保存することはできますが、OneNote のノートブックを OneDrive API を使用して操作しないでください。Note: Although OneDrive stores OneNote notebooks, you shouldn't use the OneDrive API to work with OneNote notebooks. 代わりに、OneNote API を使用します。Instead, use the OneNote API.

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

Microsoft は、ドキュメントの質を高める取り組みの一環として、ドキュメントに記載されているサンプルおよび事例の妥当性を、チェックインのたびに検証する手順を導入しています。As part of our commitment to high quality documentation, we've developed a process through which the samples and examples in our documentation are tested for validity as part of every check-in. Microsoft では、この取り組みをドキュメントの継続的検証と呼んでいます。We call this continuous documentation validation.

ドキュメントに変更を加える際は、その都度、サービスのすべてが文書化されたとおりに動作するかどうかが検証されます。Each time a change to our documentation is made, we validate that everything works as documented in the service. サービスの新しいビルドを作成するにあたっては、ドキュメント内の例を引き続き適用できるかどうかが検証されます。When we create a new build of the service, we validate that the examples in our documentation also continue to work. この取り組みは、文書化したすべての対象が適切に機能すること、新しい更新プログラムが利用可能となった後も想定どおりに機能することを保証する上で役立っています。This helps us ensure that everything we document works and works as expected even as new updates are made available.

最新のビルドの詳細については、Microsoft のドキュメント リポジトリに関する AppVeyor のビルドの状態ページを参照してください。For the latest build details, check out the AppVeyor build status page for our documentation repository.

以下のトピックで、OneDrive API に当てはまるその他のコンセプトの概要を紹介しています。The following topics contain high level overviews of other concepts that apply to the OneDrive API.