探索サービス REST API リファレンス
適用対象: Office 365
注意
Office 365 探索サービスと SDK for .NET は、2018 年 1 月 10 日から順次廃止となり、2019 年 11 月 1 日をもって完全に使用停止になります。 Microsoft Graph の使用を開始して、単一エンドポイントで Office 365 のデータにアクセスしてください。 詳細については、当社の お知らせを参照してください。
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/me | Office 365 API のリリース済みバージョンのサービスごとに 1 つの API エンドポイントをサポートします。 OData v4を返します（デフォルトでhttps://www.odata.org/documentation/odata-version-4-0/)）。 |
| https://api.office.com/discovery/v2.0/me | Office 365 API のリリース済みバージョンのサービスごとに複数の API エンドポイントをサポートします。 OData v4を返します（デフォルトでhttps://www.odata.org/documentation/odata-version-4-0/)）。 |
探索サービスの操作
最初のサインイン
最初にサインインすると、クライアントにはユーザーがアカウント情報を入力する Web ページが表示されます。アカウント情報を入力すると、探索サービスを続行するために必要なエンドポイントが返されます。これは、ユーザーが最初にアプリケーションを試す際にのみ使用されます。
アプリケーションを示します。
- ユーザーが属しているクラウドについて
- アプリケーションがユーザー ログインを送信できます。
- トークンを取得する
| パラメーター | 型 | 説明 |
|---|---|---|
scope |
文字列 | スペースで区切られた capability.operation トークンの一覧。 このスコープは、Office 365 の表記方法で表されます。 例: MyFiles.Write or Mail.Read |
redirect_uri |
文字列 | 承認が完了した後のリダイレクト先 URI。 例: https://contoso.com/continue |
lcid |
文字列 | オプション。 電子メールの HRD UI をローカライズするための 10 進数の LCID です。 例: 1031 注意 この API は、意図的にユーザーの電子メールを受け入れないようにしています。ユーザーの電子メールを現在のドメインから送信すると、ユーザーのプライバシーが侵害される可能性があるためです。 |
| 応答 | 説明 |
|---|---|
302 検出 |
応答本文には、アプリとユーザーに関する値が含まれています。 |
| 応答本文の項目 | 説明 |
|---|---|
| Location: リダイレクト URI | 承認が完了した後のリダイレクト先 URI。 |
| ?メールアドレス=... | ユーザーが入力した電子メール アドレス。 |
| &アカウント型= ... | 1 - Microsoft アカウント (Live) 2 - 組織のアカウント (Office 365) |
| &認証サービス=... | ククライアントが承認コードを取得できるエンドポイント URL。 |
| &トークンサービス=... | クライアントがアクセス トークンとリフレッシュ トークンの承認コードを交換可能なエンドポイント URL。 |
| &スコープ=... | ターゲット領域に変換された元のスコープ。クライアントに必要な情報は、Office 365 のスコープの表記方法のみです。ターゲット領域が Live の場合、元の Office 365 のスコープは Live の表記方法に変換されます。 |
| &サポート対象外のスコープ=... | 変換できないスコープ項目がある場合、それらの項目は変更されずに unsupported_scope にコンパイルされます。これは、各承認サービスが自身の表記方法でスコープを理解するために必要です。Office 365 承認サービスではスコープ パラメーターを受け入れないため、scope と unsupported_scope はどちらも空の状態で返されます。 |
| &探索サービス=... | クライアントがターゲット サービスを探索できるエンドポイント URL。 |
| &探索リソース =... | 探索サービスのリソース 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 |
| パラメーター | 型 | 説明 |
|---|---|---|
$select |
文字列 | オプション。 コンマで区切られたオブジェクト プロパティの一覧。 サービスは、選択されたプロパティだけを投影します。 これは、アプリで使用されないプロパティをダウンロードしないようにすることで、帯域幅を節約するために使用されます。 詳細については、「 https://www.odata.org/docs/ 」を参照してください。 例: 能力、サービスURI |
$filter |
文字列 | 省略可能。 元の結果セットをフィルターする OData 述語。 アプリで使用されないオブジェクト インスタンスをダウンロードしないようにすることで、帯域幅を節約するために使用されます。 使用可能な述語関数については、「ドキュメンテーション」タブの下にある「https://www.odata.org」をご覧ください。 |
| 応答 | 意味 | 説明 |
|---|---|---|
200 |
了承 | 応答本文には、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 |
| パラメーター | 型 | 説明 |
|---|---|---|
$select |
文字列 | 省略可能です。オブジェクトのプロパティのコンマ区切りのリストです。により、選択したプロパティのみをプロジェクトにサービス。アプリで使用されないプロパティをダウンロードしないようにすることで、帯域幅を節約するために使用されます。参照してください https://www.odata.org/docs/。 例: 能力、サービスURI |
$filter |
文字列 | 省略可能。 元の結果セットをフィルターする OData 述語。 アプリで使用されないオブジェクト インスタンスをダウンロードしないようにすることで、帯域幅を節約するために使用されます。 使用可能な述語関数については、「ドキュメンテーション」タブの下にある「https://www.odata.org」をご覧ください。 |
| 応答 | 意味 | 説明 |
|---|---|---|
200 |
OK | 応答本文には、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;
サービス情報 スキーマ
/services API と /allservices API は、応答本文で ServiceInfo エントリを使用します。
| プロパティ | 型 | 例 |
|---|---|---|
| 能力 | 文字列 | MyFiles |
| serviceId | 文字列 | |
| serviceName | 文字列 | O365_SHAREPOINT |
| サービス エンドポイント URI | 文字列 | https://contoso-my.sharepoint.com/personal/alexd_contoso_com |
| サービス リソース ID | 文字列 | https://contoso-my.sharepoint.com |