Table of contents
TOC
目次を折りたたむ
目次を展開する
最終更新日: 2017/11/17

探索サービス REST API リファレンス

適用対象: Office 365

Office 365 探索サービスを使用する

Office 365 探索サービスと SDK for .NET は、2018 年 1 月 10 日から順次廃止となり、2019 年 11 月 1 日をもって完全に使用停止になります。 Microsoft Graph の使用を開始して、単一エンドポイントで Office 365 のデータにアクセスしてください。 詳細については、このお知らせをご覧ください。

探索サービス API と対話するには、HTTP および OData 要求を送信します。 探索サービスでは、予定表連絡先メールMyFiles (OneDrive および OneDrive for Business のサービス エンドポイントの場合)、ノート (OneNote の場合)、および RootSite (SharePoint の場合) の探索をサポートしています。

探索サービスのリソース ID は、ResourceId = https://api.office.com/discovery/ です。

探索サービス API を使用して、Office 365 API によってアクセスするサービスのエンドポイントを見つける方法については、「Office 365 API:探索サービスの使用方法」および「Office 365 探索サービスのサンプル」のサンプル コードを参照してください。

探索サービスは、Office 365 オンライン環境向けの機能のみを提供しています。オンプレミスの展開には利用できません。

バージョン管理

探索サービスのバージョンは、次のとおりです。

探索サービス API エンドポイント説明
https://api.office.com/discovery/v1.0/meOffice 365 API のリリース済みバージョンのサービスごとに 1 つの API エンドポイントをサポートします。
既定では、OData v4 (http://www.odata.org/documentation/odata-version-4-0/) を返します。
https://api.office.com/discovery/v2.0/meOffice 365 API のリリース済みバージョンのサービスごとに複数の API エンドポイントをサポートします。
既定では、OData v4 (http://www.odata.org/documentation/odata-version-4-0/) を返します。

探索サービスの操作

最初のサインイン

最初にサインインすると、クライアントにはユーザーがアカウント情報を入力する Web ページが表示されます。アカウント情報を入力すると、探索サービスを続行するために必要なエンドポイントが返されます。これは、ユーザーが最初にアプリケーションを試す際にのみ使用されます。このエンドポイントは、アプリケーションに次の情報を提供します。

  1. ユーザーが属しているクラウドについて
  2. ログインするユーザーをアプリがリダイレクトできる場所
  3. トークンを取得する場所

パラメーター説明
scopestringスペースで区切られた capability.operation トークンの一覧。 このスコープは、Office 365 の表記方法で表されます。
例: MyFiles.Write or Mail.Read
redirect_uristring承認が完了した後のリダイレクト先 URI。
例: https://contoso.com/continue
lcidstringオプション。 電子メールの HRD UI をローカライズするための 10 進数の LCID です。
例: 1031

注意 この API は、意図的にユーザーの電子メールを受け入れないようにしています。ユーザーの電子メールを現在のドメインから送信すると、ユーザーのプライバシーが侵害される可能性があるためです。
応答説明
302 検出応答本文には、アプリとユーザーに関する値が含まれています。
応答本文の項目説明
Location: redirect_URI承認が完了した後のリダイレクト先 URI。
?user_email=...ユーザーが入力した電子メール アドレス。
&account_type=...1 - Microsoft アカウント (Live)
2 - 組織のアカウント (Office 365)
&authorization_service=...ククライアントが承認コードを取得できるエンドポイント URL。
&token_service=...クライアントがアクセス トークンとリフレッシュ トークンの承認コードを交換可能なエンドポイント URL。
&scope=...ターゲット領域に変換された元のスコープ。クライアントに必要な情報は、Office 365 のスコープの表記方法のみです。ターゲット領域が Live の場合、元の Office 365 のスコープは Live の表記方法に変換されます。
&unsupported_scope=...変換できないスコープ項目がある場合、それらの項目は変更されずに unsupported_scope にコンパイルされます。これは、各承認サービスが自身の表記方法でスコープを理解するために必要です。Office 365 承認サービスではスコープ パラメーターを受け入れないため、scope と unsupported_scope はどちらも空の状態で返されます。
&discovery_service=...クライアントがターゲット サービスを探索できるエンドポイント URL。
&discovery_resource=...探索サービスのリソース ID。探索サービスに対するトークン要求の一部として、トークン サービスに渡される必要があります。

すべての情報は、このユーザー アカウントに対して静的です。 そのためクライアントはその情報をキャッシュに入れて再使用し、ユーザーが不要な UI で混乱しないようにする必要があります。

例:

var firstSignInUri = new Uri(string.Format("https://api.office.com/discovery/v1.0/me/FirstSignIn?redirect_uri={0}&scope={1}", TerminalUriText, Scope));
var terminalUri = new Uri(TerminalUriText);

//Starting authorization
var webAuthResult = await WebAuthenticationBroker.AuthenticateAsync(WebAuthenticationOptions.None, firstSignInUri, terminalUri)
   .AsTask().ConfigureAwait(continueOnCapturedContext: true);

//Authorization finished
If (webAuthResult.ResponseStatus == WebAuthenticationStatus.Success)
{
var userEmail = MyExtractParamter("user_email",webAuthResult.ResponseData);
var accountType = MyExtractParamter("account_type",webAuthResult.ResponseData);
var authorizationService = MyExtractParamter("authorization_service",webAuthResult.ResponseData);
var tokenService = MyExtractParamter("token_service", webAuthResult.ResponseData);
var discoveryService = MyExtractParamter("discovery_service", webAuthResult.ResponseData);
var scope = MyExtractParamter("scope",webAuthResult.ResponseData);
var unsupportedScope = MyExtractParamter("unsupported_scope", webAuthResult.ResponseData);

MyCacheUserInfo(...);
}

特定のサービスを探索する

/Services API を使用して、特定のサービスのエンドポイントを取得します。


ヘッダー説明
Authorization承認フェーズで取得されたアクセス トークン。
例: Authorization: BEARER 2YotnFZFEjr1zCsicMWpAA...
Accept省略可能。このヘッダーは、応答ペイロードの形式を制御します。
Atom の場合: application/atom+xml

JSON の場合: application/json;odata=verbose

このヘッダーを省略した場合の既定値は、Atom です。

例: Accept: application/json;odata=verbose
パラメーター説明
$selectstringオプション。 コンマで区切られたオブジェクト プロパティの一覧。 サービスは、選択されたプロパティだけを投影します。 このパラメーターは、アプリで使用されないプロパティをダウンロードしないようにすることで、帯域幅を節約するために使用されます。 http://www.odata.org/docs/ をご覧ください。
例: Capability、ServiceUri
$filterstringオプション。元の結果セットをフィルター処理するための OData 述部。アプリで使用しないオブジェクト インスタンスをダウンロードしないようにして、帯域幅を節約するために使用します。使用可能な述部関数については、http://www.odata.org の [Documentation] タブを参照してください。
応答意味説明
200OK応答本文には、OData 要求に従って投影、フィルター処理、エンコードされた ServiceInfo スキーマ エントリの一覧が含まれています。 ServiceInfo スキーマの定義を参照してください。

例:

var url = string.Format("https://api.office.com/discovery/v1.0/me/services", discoveryService);

var request = HttpWebRequest.CreateHttp(url);
request.Method = "GET";
request.Headers["Authorization"] = "Bearer " + accessToken;

var response = await request.GetResponseAsync().ConfigureAwait(continueOnCapturedContext: true) as HttpWebResponse;

探索可能なサービスを調べる

/allservices API を使用して、探索可能な機能と、それらの機能を実装するサービスを調べます。 /AllServices は、匿名要求を受け入れるため、アクセス トークンを必要としません。


ヘッダー説明
Accept省略可能。このヘッダーは、応答ペイロードの形式を制御します。
Atom の場合: application/atom+xml

JSON の場合: application/json;odata=verbose

このヘッダーを省略した場合の既定値は、Atom です。

例: Accept: application/json;odata=verbose
パラメーター説明
$selectstringオプション。オブジェクト プロパティのコンマ区切りリスト。サービスでは、選択したプロパティのみがプロジェクトの対象になります。アプリで使用しないプロパティをダウンロードしないようにして、帯域幅を節約するために使用します。http://www.odata.org/docs/ を参照してください。例: Capability,ServiceUri
$filterstringオプション。元の結果セットをフィルター処理するための OData 述部。アプリで使用しないオブジェクト インスタンスをダウンロードしないようにして、帯域幅を節約するために使用します。使用可能な述部関数については、http://www.odata.org の [Documentation] タブを参照してください。
応答意味説明
200OK応答本文には、OData 要求に従って投影、フィルター処理、エンコードされた ServiceInfo スキーマ エントリの一覧が含まれています。 ServiceInfo スキーマの定義を参照してください。

例:

var request = HttpWebRequest.CreateHttp("https://api.office.com/discovery/v1.0/me/services");
request.Method = "GET";
request.Headers["Accept"] = "application/json;odata=verbose";

var response = await request.GetResponseAsync().ConfigureAwait(continueOnCapturedContext: true) as HttpWebResponse;

ServiceInfo スキーマ

/services API/allservices API は、応答本文で ServiceInfo エントリを使用します。


プロパティ
capabilityStringMyFiles
serviceIdString
serviceNameStringO365_SHAREPOINT
serviceEndpointUriStringhttps://contoso-my.sharepoint.com/personal/alexd_contoso_com
serviceResourceIdStringhttps://contoso-my.sharepoint.com

その他のリソース

© 2018 Microsoft