Web API を使用して組織の URL を検出します
Dynamics 365 for Customer Engagement Web API の探索サービスにより、アプリケーションは、ログオンしたユーザーが属する組織 (インスタンスとも呼ばれます) を実行中に判断できます。 インスタンス サービス URL、Customer Engagement リリース バージョン、インスタンスの ID などの、これらのインスタンスに関する詳細情報を取得できます。 標準 $filter および $select パラメーターを Web API サービス要求に使用して、返されたインスタンス データのリストをカスタマイズできます。
Note
オンラインユーザに適用可能なドキュメントが、 Power Apps ドキュメントが利用できるようになりました: Web API を使用した自社組織のURLを検出する.
インスタンス URL が将来的に変わる可能性がある場合、クライアント アプリケーションは Customer Engagement インスタンスにアクセスする必要があります。 たとえば、Customer Engagement インスタンスが、1 つの オンプレミス データセンターから別のデータセンターに移る場合。 検出サービスは、クライアント インスタンスが、インスタンス ID またはインスタンスの一意の名前を保持し、探索サービスを使用して現在のインスタンスのアクセス URL を検索できるようにします。
探索サービスによって提供された情報
組織情報は、探索サービスの Instance エンティティに保存されます。 そのエンティティに含まれている情報を表示するには、まずインスタンスの 1 つのサービスに HTTP GET 要求を送信します。
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')
上記の例では、探索サービスを使用して、「myorg」という一意の名前のインスタンスの組織情報を取得しています。 この要求に関する詳細については、このトピックの後半で詳しく説明します。
返される情報のスコープ
地域的探索サービスの場合、 Instances エンティティ セットは、フィルターが適用されない場合、特定の地域のユーザーがアクセスする一連のインスタンスを返します。 次の説明に従って、返されたデータのスコープがあります。
ユーザー アカウントが無効の場合、インスタンスは含まれません。
インスタンス セキュリティ グループに基づいて、ユーザーがフィルターによって除外された場合、インスタンスは含まれません。
ユーザーが代理管理者であるためアクセス権を持っている場合、インスタンスは含まれません。
呼び出し元ユーザーがインスタンスへのアクセス権を持っていない場合は、応答は、空のリストを返します。
探索サービスへのアクセス方法
一般に、探索サービスの Web API アドレスには、次の形式があります。 <service base address>/api/discovery/。 展開の種類ごとのアドレスは以下のように識別します。 設定 > カスタマイズ > 開発者リソースに移動して、Customer Engagement Web アプリケーションで、展開の Web API アドレスおよびバージョン番号を簡単に検索できます。
設置型または IFD 展開の場合の探索サービスのサービス ベース アドレスは、http[s]://{servername}/ または http[s]://dev.{servername}/ です。 この結果、http[s]://{servername}/api/discovery/ or http[s]://dev.{servername}/api/discovery/ のサービス アドレスになります。
探索サービスの使用
Instances という名前のエンティティ セットを使用して、インスタンス情報を取得します。 返されたデータをフィルター処理するようにセットされたインスタンス エンティティで$select と $filter を使用できます。 または $metadata を使用して、サービスのメタデータ ドキュメントを取得できます。
認証
オンプレミス型、あるいは Discovery OData V4 RESTful API のインスタンスでは、信頼性の高いトークン プロバイダからの統合 Windows 認証(IWA)、または OAuth トークンのいずれかに対応する、導入環境の認証モデルを採用しています。 Web アプリケーションセッション認証はサポートされていません。
Web API バージョン
データセンターまたは設置型/IFD の探索サービスのバージョンはサポートされており、組織サービスで使用されるバージョン番号と一致しています。 たとえば、次のようなものです。
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')
CORS サポート
探索サービス RESTful API は、Web API のように、クロス オリジン アクセスの CORS 規格に対応しています。 CORS サポートの詳細については、OAuth を使用するクロス オリジン リソース共有を使用して単一ページのアプリケーションへ接続する を参照してください。
例
特定のインスタンスの詳細を取得します。 GUID を省くと、認証されたユーザーがアクセスできるすべてのインスタンスが返されます。
GET https://dev.{servername}/api/discovery/v9.1/Instances(<guid>)代替キーとして UniqueName 属性を使用できます。
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')運用の種類によってフィルター処理された、利用可能なインスタンスのリストを取得します。
GET https://dev.{servername}/api/discovery/v9.1/Instances?$select=DisplayName,Description&$filter=Type+eq+0特定のインスタンスの ID プロパティの値を取得します。
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')/Id/$value