OneDrive 上のドライブ内のリソースをアドレス指定する

  • [アーティクル]

OneDrive API を使用すると、1 つの URL でリソースの 2 つの側面を扱うことができます。

  • driveItem リソース
  • アイテムの特性、ファセット、またはリレーションシップ

アイテム ファセットは、イメージのメタデータ、フォルダーのメタデータなどのリソースの要素を表します。

この例では、ファイルの標準 URL は次のようになります。

https://graph.microsoft.com/v1.0/me/drive/root:/Documents/MyFile.xlsx:/content

この URL の例には、次のコンポーネントがあります。

  • https://graph.microsoft.com/v1.0 - 使用されている Microsoft Graph のバージョン。
  • /me - アドレス指定される最上位の Microsoft Graph リソース。この場合は現在のユーザー。
  • /drive - 以前のリソースの既定のドライブ。この場合はユーザーの OneDrive。
  • /root - ドライブのルート フォルダー。
  • :/Documents/MyFile.xlsx: - /Documents/MyFile.xlsx の前後の : : は、パスベースのアドレス指定構文への切り替えを表します。 2 つのコロンの間にあるものはすべて、パスの前のアイテムからの相対パスとして扱われます (この場合は root)。
  • /content - ファイルの既定のバイナリ ストリームを表します。 アイテムの別のプロパティやリレーションシップにアドレス指定することもできます。

ID ベースのアドレス指定

OneDrive では、アイテムの ID をベースにしたアドレス指定をサポートしています。 アイテムは作成時に一意の識別子が割り当てられます。この ID は、ユーザーがアイテムに対して実行したアクション全体にわたって保持されます。 アイテムの名前を変更したり移動した場合でも、アイテムの ID は変更されません。

ID ベースのアドレス指定は、ユーザーが OneDrive 上の別の場所に移動した可能性のあるアイテムの追跡に役立つ方法です。 アイテムの ID があり、そのアイテムが存在する限り、ユーザーはアイテムを検索することができます。

パスベースのアドレス指定

OneDrive では、パスベースのアドレス指定もサポートしています。 これにより、わかりやすい URL 構文を使用して、OneDrive で表示されるアイテムの階層を基準にしたアイテムのアドレス指定が可能になります。 アイテムの階層がわかっている場合は、階層の各レベルを検出するために時間を費やして何度も呼び出しを繰り返す必要なしに、そのアイテムに直接アドレス指定することができます。

ただし、パスベースのアドレス指定はアイテムの名前を基にしているため、アイテムの名前を変更したり、新しい場所にアイテムを移動すると、アイテムのパスが変更されることになります。

パスベースのアドレス指定は、OneDrive の任意のアイテムに関連して使用できます。これにより、いくつかの非常に有用なシナリオが可能になります。 たとえば、共有フォルダーを使用するときに、共有フォルダーのアイテムの ID に関連するパスベースの URL を使用して、共有フォルダー内のものをパスで指定できます。

例

これらの例は、データへのアクセスに使用できるさまざまな URL 形式を示しています。 これらの URL はすべて論理的に同等であり、MyFile.xlsx のコンテンツを返します。

URL の例 説明
/drive/root:/Documents/MyFile.xlsx:/content ドライブのルートからの相対パスで指定します。
/drive/special/documents:/MyFile.xlsx:/content documents の特定のフォルダー内のファイル名で指定します。
/drive/items/0123456789AB/content アイテムの ID で指定します。
/drives/AB0987654321/items/0123456789AB/content ドライブの ID とアイテムの ID で指定します。

パスのエンコード

OneDrive では、ユーザーの OneDrive 内のアイテムのパスを使用して、ファイルとフォルダーのアドレス指定をサポートします。 ただし、パスには URL 保護されていない文字が含まれる可能性のあるユーザー指定のコンテンツが含まれているため、パス セグメントの適切なエンコードを行う必要があります。

Microsoft Graph では、URL が RFC 3986 に準拠していることを想定します。 Microsoft Graph のパスを適切にエンコードする方法を次に要約します。

OneDrive の予約文字

次の文字は OneDrive の予約文字です。OneDrive のフォルダーやファイル名には使用できません。

  onedrive-reserved  = "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|"
  onedrive-business-reserved
                     = "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|" / "#" / "%"

注: フォルダー名の最後はピリオド (.) にできません。

注: OneDrive for Business のファイルまたはフォルダー名は、チルダ ('~') で始めることはできません。 詳細については、「OneDrive for Business を介して SharePoint ライブラリをコンピューターに同期する際の制限事項」を参照してください。

URI パス文字

OneDrive API の URI のパス セグメントを構築するときには、URI RFC に基づいて、パス名に次の文字を使用できます。

  pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
  pct-encoded = "%" HEXDIG HEXDIG
  unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
  sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

# や (スペース) など、pchar グループに含まれないアイテム名の文字は、パーセントでエンコードされる必要があります。

文字のエンコード

Microsoft Graph では標準のパーセント エンコーディングを使用します。つまり、URL 無効文字は % の後にその文字の UTF-8 文字コードでエンコードされます。 以下に例を示します。

  • " " ->%20
  • "#" ->%23

URL エンコードの一般的な間違い

1 回の呼び出しで URL 全体をエンコードすることはできません。エンコード規則が URL のセグメントごとに異なるためです。 適切なエンコードが行われていない場合、どのセグメントにどのコンテンツが含まれているのか、エンコードされていない URL が曖昧になります。 そのため、URL 文字列の作成時に URL パスをエンコードする必要があります。

たとえば、次のように記述する代わりに

string url = url_encode("https://api.onedrive.com/v1.0/drive/root:/" + path + ":/children")

次のように記述します。

string url = "https://api.onedrive.com/v1.0/drive/root:/" + url_path_encode(path) + ":/children")

ただし、すべての URL エンコード ライブラリが、標準的な URL パス エンコードのすべての要件を遵守しているわけではありません。

.NET/C#/Visual Basic

HttpUtility と Uri の.NET クラスには、URL エンコードのさまざまなメソッドが含まれています。 ただし、これらのメソッドは、どれも URL のパス コンポーネント (HttpUtility.UrlPathEncode を含む) のすべての予約文字を正しくエンコードすることはできません。

これらのメソッドを使用する代わりに、UriBuilder を使用して適切にエスケープされた URL を作成する必要があります。

UriBuilder builder = new UriBuilder("https://api.onedrive.com");
builder.Path = "/v1.0/drive/root:/Documents/My Files/#nine.docx";
Uri url = builder.Uri;

Objective-C/iOS

Objective-C、iOS、Mac OS X の開発では、stringByAddingPercentEncodingWithAllowedCharacters メソッドと [NSCharacterSet URLPathAllowedCharacterSet] を使用して、URL のパス コンポーネントを適切にエンコードします。

NSString *root = @"https://api.onedrive.com/v1.0/drive/root:/";
NSString *path = @"Documents/My Files/#nine.docx";
NSString *encPath = [path stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLPathAllowedCharacterSet]];
NSURL *url = [[NSURL alloc] initWithString:[root stringByAppendingString:encPath]];

Android

Uri.Builder クラスを使用して、適切にエンコードされた URL を作成します。

Uri.Builder builder = new Uri.Builder();
builder.
  scheme("https").
  authority("api.onedrive.com").
  appendPath("v1.0").
  appendPath("drive").
  appendPath("root:").
  appendPath("Documents").
  appendPath("My Files").
  appendPath("#nine.docx");
String url = builder.build().toString();

JavaScript

JavaScript で escape() を使用して、パス コンポーネントを適切にエンコードします。

var root = "https://api.onedrive.com/v1.0/drive/root:";
var path = "/Documents/My Files/#nine.docx";
var url = root + escape(path);

例

以下のフォルダー階層を持つ OneDrive ユーザー (Ryan) の例を次に示します。

OneDrive
	\Ryan's Files
		\doc (1).docx
    \estimate%s.docx
	\Break#Out
		\saved_game[1].bin

次に示すように、Ryan の各ファイルにアドレス指定するには、パーセント エンコードを使用します。

パス パスのエンコードされた URL
\Ryan's Files /root:/Ryan's%20Files
\...\doc (1).docx /root:/Ryan's%20Files/doc%20(1).docx
\...\estimate%.docx /root:/Ryan's%20Files/estimate%25s.docx
\Break#Out /root:/Break%23Out
\...\saved_game[1].bin /root:/Break%23Out/saved_game[1].bin