Detecte la dirección URL de su organización con la API web.

Se aplica a las aplicaciones Dynamics 365 for Customer Engagement, versión 9.x

El Servicio de detección para la API web de aplicaciones 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. Todos los tipos de implementación de Customer Engagement admiten el servicio de detección: Online, local e IFD.

Las aplicaciones de clientes 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 de aplicaciones Dynamics 365 for Customer Engagement 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.

Servicio de detección global

Además de los servicios de detección específicos del centro de datos (regionales), que están disponibles en el extremo 2011 (SOAP) y a través de la API web, también hay un servicio de detección global de la API web que abarca todos los centros de datos operativos. Para obtener información sobre los servicios de detección regionales en el extremo 2011, consulte Descubrir la dirección URL de la organización mediante la utilización del servicio de detección

Nota

Se recomienda que los usuarios cambien del antiguo servicio de detección regional (https://disco.crm.dynamics.com) al servicio de detección global (https://globaldisco.crm.dynamics.com).

Para usuarios de Dynamics 365 US Government, el servicio de detección global está disponible sólo para usuarios de GCC y la dirección URL es https://globaldisco.crm9.dynamics.com. Más información: Direcciones URL de Dynamics 365 Government.

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://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')  

En el ejemplo anterior, el servicio de detección global de aplicaciones Dynamics 365 for Customer Engagement 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 global, el conjunto de entidades Instances devuelve el conjunto de instancias al que el usuario tiene acceso en todas las geografías, cuando no se aplica ningún filtro. Los datos de devolución tiene un ámbito como se describe a continuación.

  • Incluye todas las instancias en la nube comercial donde el usuario se aprovisiona y habilita, salvo que no se devuelven instancias de nubes soberanas

  • 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

Dynamics 365 for Customer Engagement Servicios de detección

La dirección base del servicio de detección global es: https://globaldisco.crm.dynamics.com/. Esto da como resultado la dirección de servicio de https://globaldisco.crm.dynamics.com/api/discovery/.

La dirección base del servicio de detección global para un centro de datos es: https://disco.crm[N].dynamics.com/. Esto da como resultado la dirección del servicio de detección de https://disco.crm[N].dynamics.com/api/discovery/. Cada centro de datos tiene un número N asociado. Para obtener una lista de centros de datos de aplicaciones Dynamics 365 for Customer Engagement disponibles y sus números N, vea Descargar los extremos usando la página de recursos para programadores.

Servicio de detección IFD y local

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 la API web de aplicaciones Dynamics 365 for Customer Engagement del servicio de detección requieren autenticación con tokens de acceso de OAuth. Las instancias de IFD o locales de la API web 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.

Cuando se configura el servicio de detección para la autenticación de OAuth, una solicitud enviada a la API web de servicio sin un token de acceso desencadena un desafío del portador con la autoridad del extremo "común" y el id. de recurso del servicio. De manera similar, cuando se configura una implementación local para OAuth, un desafío del portador devuelve la dirección URL de la entidad local y el id. de recurso del servicio.

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. Sin embargo, el servicio de detección global de aplicaciones Dynamics 365 for Customer Engagement no está vinculado al número de versión de la implementación de Customer Engagement. En su lugar, el servicio global usa sus propios números de versión. En el momento de redactar este documento,el servicio de detección global de aplicaciones Dynamics 365 for Customer Engagement es la versión 1.0 (v1.0). Por ejemplo:

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

Soporte técnico de CORS

La API web 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 a aplicaciones Dynamics 365 for Customer Engagement.

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://disco.crm.dynamics.com/api/discovery/v8.1/Instances(<guid>)  
    GET https://dev.crm.external.contoso.com/api/discovery/v8.1/Instances(<guid>)  
    
  • Puede usar el atributo UniqueName como clave alternativa.

    GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')  
    
  • Recupere una lista de instancias disponible, filtrada por tipo de producción.

    GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0   
    
  • Recupere el valor de la propiedad del id. de la instancia específica.

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