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

ID ベースとパスベースのアドレス指定を使用して OneDrive 上のドライブ内の項目にアクセスする方法と、Microsoft Graph 用にパスを適切にエンコードする方法について説明します。

ID ベースのアドレス指定

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

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

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

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

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

OneDrive の任意のアイテムに関連するパス ベースのアドレス指定を使用できます。 たとえば、共有フォルダーを使用するときに、共有フォルダーのアイテムの ID に関連するパスベースの URL を使用して、共有フォルダー内のものをパスで指定できます。

例

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

パスのエンコード

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

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

OneDrive の予約文字

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

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

URI パス文字

Microsoft Graph 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://graph.microsoft.com/v1.0/me/drive/root:/" + path + ":/children")

次のように記述します。

string url = "https://graph.microsoft.com/v1.0/me/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://graph.microsoft.com");
builder.Path = "/v1.0/me/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://graph.microsoft.com/v1.0/me/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("graph.microsoft.com").
  appendPath("v1.0").
  appendPath("me").
  appendPath("drive").
  appendPath("root:").
  appendPath("Documents").
  appendPath("My Files").
  appendPath("#nine.docx");
String url = builder.build().toString();

JavaScript

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

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

例

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

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

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

関連コンテンツ

• OneDrive ファイル ストレージ API の概要