Web API を使用して組織の URL を検出します

  • [アーティクル]

 

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

Microsoft Dynamics 365 Web API の探索サービスにより、アプリケーションは、ログオンしたユーザーが属する組織 (インスタンス とも呼ばれます) を実行中に判断できます。 インスタンス サービス URL、Dynamics 365 リリース バージョン、インスタンスの ID などの、これらのインスタンスに関する詳細情報を取得できます。 標準 $filter および $select パラメーターを Web API サービス要求に使用して、返されたインスタンス データのリストをカスタマイズできます。 探索サービスは Online、設置型、および IFD のすべての Dynamics 365 展開形式でサポートされます。

インスタンス URL が時と共に変化する可能性がある場合、クライアント アプリケーションは Dynamics 365 にアクセスする必要があります。 たとえば、Dynamics 365 インスタンスが、1 つの Microsoft Dynamics 365 (オンライン) データセンターから別のデータセンターに移る場合。 検出サービスは、クライアント インスタンスが、インスタンス ID またはインスタンスの一意の名前を保持し、探索サービスを使用して現在のインスタンスのアクセス URL を検索できるようにします。

データセンター固有の探索サービスに加え、2011 (SOAP) エンドポイントで、Web API を通じて、すべての運用データセンター全体にまたがる Web API のみのグローバル探索サービスもあります。 2011 エンドポイントの探索サービスの詳細については、「組織サービスを使用して組織の URL を検出する」を参照してください。

探索サービスによって提供された情報

組織情報は、探索サービスの Instance エンティティに保存されます。 そのエンティティに含まれている情報を表示するには、まずインスタンスの 1 つのサービスに HTTP GET 要求を送信します。

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

上の例では、Microsoft Dynamics 365 (オンライン) のグローバル探索サービスを使用して、「myorg」という一意の名前のインスタンスの組織情報を取得します。 この要求に関する詳細については、このトピックの後半で詳しく説明します。

返される情報のスコープ

グローバル探索サービスの場合、Instances エンティティ セットは、フィルターが適用されない場合、すべての地域のユーザーがアクセスするインスタンスのセットを返します。 次の説明に従って、返されたデータのスコープがあります。

  • 主権あるクラウド インスタンスが返されないことを除き、ユーザーに対してプロビジョニングされ、有効化された商用クラウド内のすべてのインスタンスが含まれます

  • ユーザー アカウントが無効の場合、インスタンスは含まれません。

  • インスタンス セキュリティ グループに基づいて、ユーザーがフィルターによって除外された場合、インスタンスは含まれません。

  • ユーザーが代理管理者であるためアクセス権を持っている場合、インスタンスは含まれません。

  • 呼び出し元ユーザーがインスタンスへのアクセス権を持っていない場合は、応答は、空のリストを返します。

探索サービスへのアクセス方法

一般に、探索サービスの Web API アドレスには、次の形式があります。 <service base address>/api/discovery/。 展開の種類ごとのアドレスは以下のように識別します。[設定] > [カスタマイズ] > [開発者リソース] に移動して、Dynamics 365 Web アプリケーションで、展開の Web API アドレスおよびバージョン番号を簡単に検索できます。

Dynamics 365 (オンライン) Discovery の各種サービス

グローバル検索サービスのサービス ベース アドレスは、https://globaldisco.crm.dynamics.com/ です。 この結果、https://globaldisco.crm.dynamics.com/api/discovery/ のサービス アドレスになります。

データセンターの検索サービスのサービス ベース アドレスは、https://disco.crm[N].dynamics.com/ です。 この結果、https://disco.crm[N].dynamics.com/api/discovery/ の検索サービス アドレスになります。 各データセンターに関連付けられる N 番号があります。 使用可能な Microsoft Dynamics 365 (オンライン) データセンターの完全なリスト、および N 番号に関しては、「Microsoft Dynamics 365 の [開発者リソース] ページを使用してエンドポイントをダウンロードする」を参照してください。

設置型および IFD の探索サービス

設置型または IFD 展開の場合の探索サービスのサービス ベース アドレスは、http[s]://{servername}/ または http[s]://dev.{servername}/ です。 この結果、http[s]://{servername}/api/discovery/ or http[s]://dev.{servername}/api/discovery/ のサービス アドレスになります。

探索サービスの使用

Instances という名前のエンティティ セットを使用して、インスタンス情報を取得します。 返されたデータをフィルター処理するようにセットされたインスタンス エンティティで**$select** と $filter を使用できます。 または $metadata を使用して、サービスのメタデータ ドキュメントを取得できます。

認証

探索サービスの Microsoft Dynamics 365 (オンライン) Web API インスタンスは、OAuth アクセス トークンを使用した証明書が必要です。 検出 Web API の設置型または IFD のインスタンスは、信頼できるトークン プロバイダーの統合 Windows 認証 (IWA) または OAuth トークンをサポートする展開の認証モデルを採用します。 Web アプリケーションセッション認証はサポートされていません。

探索サービスが、OAuth 認証用に構成されている場合、アクセス トークンなしでサービス Web API に送信される要求は、共通エンドポイントの権限およびサービスのリソース ID と共にベアラー チャレンジをトリガーします。 同様に、設置型展開が OAuth 用に構成されている場合、ベアラー チャレンジは、設置型権限 URL およびサービスのリソース ID を返します。

Web API バージョン

データセンターまたは設置型/IFD の探索サービスのバージョンはサポートされており、組織サービスで使用されるバージョン番号と一致しています。 ただし、Microsoft Dynamics 365 (オンライン) のグローバル探索サービスは、Dynamics 365 展開のバージョン番号と関連付けられていません。 代わりに、グローバル サービスは、独自のバージョン番号を使用しています。 現時点で、Microsoft Dynamics 365 (オンライン) のグローバル探索サービスはバージョン 1.0 (v1.0) です。 たとえば、次のようになります。

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

CORS サポート

探索サービス Web API は、組織サービス Web API のように、クロス オリジン アクセスの CORS 標準をサポートします。 CORS サポートの詳細については、「OAuth を使用するクロス オリジン リソース共有を使用して Microsoft Dynamics 365 の単一ページのアプリケーションへ接続する」を参照してください。

例

  • 特定のインスタンスの詳細を取得します。 GUID を省くと、認証されたユーザーがアクセスできるすべてのインスタンスが返されます。

    GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(<guid>)
GET https://dev.crm.external.contoso.com/api/discovery/v8.1/Instances(<guid>)

  • 代替キーとして UniqueName 属性を使用できます。

    GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

  • 運用の種類によってフィルター処理された、利用可能なインスタンスのリストを取得します。

    GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0

  • 特定のインスタンスの ID プロパティの値を取得します。

    GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(UniqueName='myorg')/Id/$value

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 著作権