Individuare l'URL dell'organizzazione utilizzando l'API Web

  • Articolo

 

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Il servizio di individuazione per l'API Web di Microsoft Dynamics 365 consente alle applicazioni di determinare in fase di esecuzione le organizzazioni, note anche come istanze, a cui appartiene l'utente connesso. Puoi recuperare le informazioni dettagliate sulle istanze, ad esempio l'URL del servizio istanza, la versione finale di Dynamics 365, l'ID istanza e altro ancora. Puoi utilizzare i parametri standard $filter e $select su una richiesta di servizio API Web per personalizzare l'elenco restituito dei dati dell'istanza. Il servizio di individuazione è supportato da tutti i tipi di distribuzione Dynamics 365: online, locale e IFD.

È possibile che le applicazioni client abbiano bisogno dell'accesso a un'istanza di Dynamics 365 in cui l'URL dell'istanza potrebbe cambiare nel tempo. Ad esempio, quando un'istanza di Dynamics 365 viene spostata da un data center di Microsoft Dynamics 365 (online) in un altro. Il servizio di individuazione consente all'istanza client di salvare in modo permanente l'ID istanza o il nome univoco dell'istanza e utilizzare il servizio di individuazione per la ricerca dell'URL corrente di accesso all'istanza.

Oltre ai servizi di individuazione specifici del data center disponibili nell'endpoint (SOAP) 2011 e tramite l'API Web, esiste anche un servizio globale di individuazione solo API Web che si estende per tutti i data center operativi. Per ulteriori informazioni sul servizio di individuazione dell'endpoint 2011 vedere Individuare l'URL dell'organizzazione utilizzando il Servizio organizzazione.

Informazioni fornite dal servizio di individuazione

Le informazioni sull'organizzazione sono archiviate nell'entità Instance del servizio di individuazione. Per verificare il tipo di informazioni contenute in tale entità, invia una richiesta HTTP GET al servizio per una delle istanze.

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

Nell'esempio precedente, il servizio di individuazione globale di Microsoft Dynamics 365 (online) viene utilizzato per ottenere informazioni dell'istanza con il nome univoco "myorg". Ulteriori dettagli sulla richiesta trattati più avanti in questo argomento.

Ambito delle informazioni restituite

Per il servizio di individuazione globale, il set di entità Instances restituisce il set di istanze a cui l'utente ha accesso in tutte le geografie, quando non vengono applicati filtri. I dati restituiti hanno l'ambito come descritto di seguito.

  • Include tutte le istanze nel cloud commerciale in cui l'utente è sottoposto al provisioning e abilitato, a meno che non vengano restituite le istanze di cloud sovrani

  • Non include le istanze in cui l'account utente è disabilitato

  • Non include le istanze in cui gli utenti sono stati filtrati in base a un gruppo di sicurezza istanza

  • Non include le istanze in cui l'utente ha accesso come amministratore delegato

  • Se l'utente chiamante non ha accesso ad alcuna istanza, la risposta restituisce semplicemente un elenco vuoto

Come accedere ai servizi di individuazione

L'indirizzo dell'API Web del servizio di individuazione è generalmente nel formato seguente: <service base address>/api/discovery/. Gli indirizzi per ogni tipo di distribuzione vengono identificati di seguito. Puoi trovare facilmente gli indirizzi e il numero di versione dell'API Web per la distribuzione nell'applicazione Web Dynamics 365 passando a Impostazioni > Personalizzazione > Risorse per sviluppatori

Servizi di individuazione di Dynamics 365 (online)

L'indirizzo di base del servizio di individuazione globale è: https://globaldisco.crm.dynamics.com/. L'operazione restituisce l'indirizzo del servizio https://globaldisco.crm.dynamics.com/api/discovery/.

L'indirizzo di base del servizio di individuazione per un data center è: https://disco.crm[N].dynamics.com/. L'operazione restituisce l'indirizzo del servizio di individuazione https://disco.crm[N].dynamics.com/api/discovery/. Ogni data center ha un numero N associato. Per un elenco completo dei data center di Microsoft Dynamics 365 (online) disponibili e dei numeri N, vedi Scaricare gli endpoint utilizzando la pagina delle risorse per sviluppatori Microsoft Dynamics 365.

Servizio di individuazione locale e IFD

L'indirizzo base del servizio di individuazione per una distribuzione locale o IFD è: http[s]://{servername}/ o http[s]://dev.{servername}/. L'operazione restituisce l'indirizzo del servizio http[s]://{servername}/api/discovery/ o http[s]://dev.{servername}/api/discovery/.

Usare il servizio di individuazione

Un set di entità denominato Instances è utilizzato per ottenere le informazioni sull'istanza. Puoi usare $select e $filter con il set di entità Istanze per filtrare i dati restituiti. Puoi inoltre utilizzare $metadata per ottenere il documento con i metadati del servizio.

Autenticazione

Le istanze dell'API Web di Microsoft Dynamics 365 (online) del servizio di individuazione richiedono l'autenticazione con i token di accesso OAuth. Le istanze locali o IFD dell'API Web di individuazione adottano il modello di autenticazione della distribuzione, supportando i token di Autenticazione di Windows integrata (IWA) o OAuth di un provider di token attendibile. L'autenticazione della sessione dell'applicazione Web non è supportata.

Se il servizio di individuazione è configurato per l'autenticazione OAuth, viene inviata una richiesta all'API Web del servizio senza che un token di accesso attivi la richiesta di accesso con l'autorità dell'endpoint "comune" e l'ID risorsa del servizio. Analogamente, se una distribuzione locale è configurata per OAuth, la richiesta di accesso restituisce l'URL dell'autorità locale e l'ID risorsa del servizio.

Controllo delle versioni dell'API Web

Il controllo delle versioni del servizio di individuazione del data center o locale/IFD è supportato e corrisponde alla numerazione delle versioni utilizzato dal servizio dell'organizzazione. Tuttavia, il servizio di individuazione globale di Microsoft Dynamics 365 (online) non è legato al numero di versione della distribuzione di Dynamics 365. Il servizio globale utilizza una propria numerazione della versione. Alla data del presente documento, la versione del servizio globale di individuazione Microsoft Dynamics 365 (online) individuazione è 1.0 (v1.0). Ad esempio:

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

Supporto CORS

L'API Web del servizio di individuazione supporta lo standard CORS per l'accesso tra origini come l'API Web dell'organizzazione. Per ulteriori informazioni sul supporto CORS, vedi Utilizzare OAuth con la condivisione di risorse tra origini per connettere un'applicazione su singola pagina a Microsoft Dynamics 365.

Esempi

  • Ottieni i dettagli di un'istanza specifica. Se si omette il GUID, vengono restituite tutte le istanze a cui ha accesso l'utente autenticato.

    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>)

  • Puoi utilizzare l'attributo UniqueName come chiave alternativa.

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

  • Recupera un elenco di istanze disponibili, filtrato in base al tipo di produzione.

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

  • Recupera un valore della proprietà ID dell'istanza specifica.

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

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright