웹 API를 사용하여 조직의 URL 검색

아티클
07/06/2017

게시 날짜: 2017년 1월

적용 대상: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Microsoft Dynamics 365 웹 API에 대해 이 검색 서비스를 사용하면 응용 프로그램에서 런타임에 인스턴스라고도 불리는 로그인한 사용자가 속해 있는 조직을 확인할 수 있습니다. 인스턴스 서비스URL, Dynamics 365 릴리스 버전, 인스턴스 ID 등과 같은 인스턴스에 대한 자세한 정보를 검색할 수 있습니다. Web API 서비스 요청에 표준 $filter 및 $select 매개 변수를 사용하여 반환된 인스턴스 데이터 목록을 사용자 지정할 수 있습니다. 검색 서비스는 온라인, 온-프레미스 및 IFD 등 모든 Dynamics 365 배포 유형에서 지원됩니다.

클라이언트 응용 프로그램은 인스턴스가 URL 변경될 수 있는 Dynamics 365 인스턴스에 대한 액세스가 필요할 수 있습니다. 예를 들어, 한 Dynamics 365 인스턴스를 한 Microsoft Dynamics 365(온라인) 데이터 센터에서 다른 데이터 센터로 이동하는 경우입니다. 검색 서비스로 클라이언트 인스턴스가 인스턴스 ID 또는 고유 인스턴스 이름을 유지하고 현재 인스턴스 액세스 URL 조회를 검색 서비스를 사용할 수 있습니다.

2011(SOAP) 끝점 및 웹 API에서 사용할 수 있는 데이터 센터 특정 검색 서비스 뿐만 아니라 모든 운영 데이터 센터에 걸친 웹 API만에 대한 전역 검색 서비스가 있습니다. 2011 끝점 검색 서비스에 대 한 자세한 내용은 조직 서비스를 사용하여 조직에 대한 URL을 검색합니다.를 참조하십시오.

검색 서비스에서 제공하는 정보

조직 정보는 검색 서비스의 Instance 엔터티에 저장됩니다. 해당 엔터티에 포함된 정보의 종류를 보려면 인스턴스 중 하나에 대한 서비스에 HTTP GET 요청을 보냅니다.

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

위의 예제에서 Microsoft Dynamics 365(온라인)의 전역 검색 서비스는 고유한 이름의 "myorg" 인스턴스의 조직 정보를 가져오는 데 사용됩니다. 이 요청에 대한 자세한 내용은 이 항목의 뒷부분에서 추가 설명됩니다.

반환되는 정보의 범위

전역 검색 서비스에 대해 Instances 엔터티 집합은 필터가 적용되지 않았을 때 사용자가 액세스할 수 모든 지역의 인스턴스 집합을 반환합니다. 반환되는 데이터의 범위는 아래에 기술된 것과 같습니다.

사용자가 프로비저닝 및 활성화된 상용 클라우드의 모든 인스턴스 포함. 단, 독립 클라우드 인스턴스는 반환되지 않음
사용자 계정이 비활성화된 경우는 제외
인스턴스 보안 그룹에 따라 사용자가 필터링한 인스턴스는 포함되지 않음
사용자가 위임된 관리자로서 액세스할 수 있는 인스턴스를 포함하지 않음
호출하는 사용자가 인스턴스에 액세스할 수 없는 경우 응답은 빈 목록을 반환

검색 서비스에 액세스하는 방법

일반적으로 검색 서비스의 웹 API 주소는 <service base address>/api/discovery/와 같은 형식을 띱니다. 각 배포 유형에 대한 주소는 아래에 표시됩니다. 배포에 대한 웹 API 주소와 버전 번호를 설정 > 사용자 지정 > 개발자 리소스로 이동하여 Dynamics 365 웹 응용 프로그램에서 쉽게 찾을 수 있습니다.

Dynamics 365(온라인) 검색 서비스

글로벌 검색 서비스의 서비스 기준 주소는 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/ 또는 http[s]://dev.{servername}/api/discovery/ 서비스 주소입니다.

검색 서비스 사용

Instances라는 엔터티 집합은 인스턴스 정보를 얻는 데 사용됩니다. 인스턴스 엔터티 집합과 함께 $select 및 $filter를 사용하여 반환된 데이터를 필터링할 수 있습니다. 또한 서비스의 메타 데이터 문서를 얻기 위해 $metadata를 사용할 수 있습니다.

인증

검색 서비스의 Microsoft Dynamics 365(온라인) 웹 API 인스턴스를 사용하려면 OAuth 액세스 토큰을 사용하여 인증을 해야 합니다. 검색 웹 API의 온-프레미스 또는 IFD 인스턴스는 신뢰할 수 있는 토큰 공급자로부터 통합 Windows 인증(IWA) 또는 OAuth 토큰을 지원하는 배포 인증 모델을 배포를 채택하고 있습니다. 웹 응용 프로그램 세션 인증은 지원되지 않습니다.

OAuth 인증을 위해 검색 서비스가 구성된 경우, 액세스 토큰 없이 서비스 웹 API에 보낸 요청은 서비스의 "일반적인" 끝점 및 리소스 ID의 전달자 시도/응답 권한이 부족할 수 있습니다. 마찬가지로, OAuth를 위해 온-프레미스 배포가 구성된 경우, 전달자 시도/응답이 서비스의 온-프레미스 권한 URL과 리소스 ID를 반환합니다.

웹 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 지원

검색 서비스 웹 API는 조직 서비스 웹 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

다음을 통해 공유