Detecte la dirección URL de su organización con la API web.
El Servicio de detección para la API web de Dynamics 365 for Customer Engagement permite a sus aplicaciones determinar en tiempo de ejecución las organizaciones, también conocidas como instancias, a las que pertenece el usuario que ha iniciado sesión. Puede recuperar la información detallada sobre esas instancias como la dirección URL del servicio de la instancia, la versión de Customer Engagement, el id. de instancia, etc. Puede usar los parámetros $filter y $select estándar para una solicitud de servicio de API web para personalizar la lista devuelta de datos de la instancia.
Nota
La documentación que es aplicable a los usuarios conectados está ahora disponible en la documentación de Power Apps en: Descubra la dirección URL de la organización mediante la API web.
Las aplicaciones cliente pueden necesitar acceso a una instancia de Customer Engagement donde la dirección URL de la instancia puede cambiar con el tiempo. Por ejemplo, cuando la instancia de Customer Engagement se mueve desde un centro de datos local a otro. El servicio de detección permite a la instancia de los clientes continuar con el id. de instancia o el nombre único de instancia y, a continuación, usar el servicio de detección para buscar la dirección URL de acceso de instancia actual.
Información proporcionada por el servicio de detección
La información de la organización se almacenan en la entidad Instance del servicio de detección. Para ver el tipo de información incluida en esa entidad, envíe una solicitud HTTP GET al servicio para una de sus instancia.
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')
En el ejemplo anterior, el servicio de detección se utiliza para obtener la información de la organización de la instancia con un nombre único de "myorg". Se tratará con mayor detenimiento más información acerca de esta solicitud más adelante en este tema.
Ámbito de la información devuelta
Para el servicio de detección regional, el conjunto de entidades Instances devuelve el conjunto de instancias a las que el usuario tiene acceso en un región geográfica concreta, cuando no se aplica ningún filtro. Los datos de devolución tiene un ámbito como se describe a continuación.
No incluye las instancias donde está deshabilitada la cuenta del usuario
No incluye las instancias en las que los usuarios se han filtrado basándose en un grupo de seguridad de la instancia
No incluye instancias donde el usuario tiene acceso como resultado de ser administrador delegado
Si el usuario que llama no tiene acceso a ninguna instancia, la respuesta devuelve simplemente una lista vacía
Cómo obtener acceso a los servicios de detección
En general, la dirección de la API web del servicio de detección tiene el siguiente formato: <service base address>/api/discovery/. A continuación, se identifican las direcciones para cada tipo de implementación. Encontrará con facilidad las direcciones de la API web y el número de versión para su implementación en la aplicación web de Customer Engagement si navega hasta Configuración > Personalización > Recursos de desarrollador.
La dirección base del servicio de detección para una implementación de IFD o local es: http[s]://{servername}/ o http[s]://dev.{servername}/. Esto da como resultado la dirección de servicio de http[s]://{servername}/api/discovery/ o http[s]://dev.{servername}/api/discovery/.
Uso del servicio de detección
Se usa un conjunto de entidad denominado Instances para recopilar información de la instancia. Puede usar $select y $filter con el conjunto de entidades Instancias para filtrar los datos devueltos. También puede usar $metadata para obtener el documento de metadatos del servicio.
Autenticación
Las instancias de IFD o locales de la API OData v4 RESTful de detección adoptan el modelo de autenticación de su implementación, admitiendo los tokens de OAuth o autenticación integrada de Windows (IWA) de un proveedor de tokens de confianza. La autenticación de sesión de aplicación web no es compatible.
Control de versiones de la API web
Se admite el control de versiones del servicio de detección para un centro de datos o una implementación local o de IFD y consta de números de versión como se usan por el servicio de la organización. Por ejemplo:
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')
Soporte técnico de CORS
La API RESTful del servicio de detección admite la norma CORS para acceso de origen cruzado como hace la Web API. Para obtener más información sobre el soporte técnico de CORS, consulte Usar OAuth con uso compartido de recursos entre orígenes para conectar una aplicación de una sola página.
Ejemplos
Obtenga los detalles de una instancia determinada. Si sale del GUID, se devuelven todas las instancias a las que el usuario autenticado tiene acceso.
GET https://dev.{servername}/api/discovery/v9.1/Instances(<guid>)Puede usar el atributo UniqueName como clave alternativa.
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')Recupere una lista de instancias disponible, filtrada por tipo de producción.
GET https://dev.{servername}/api/discovery/v9.1/Instances?$select=DisplayName,Description&$filter=Type+eq+0Recupere el valor de la propiedad del id. de la instancia específica.
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')/Id/$value