Finde URL-adressen til din organisation ved hjælp af Web API'en

Artikel
07/06/2017

Udgivet: januar 2017

Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Registreringstjenesten for Microsoft Dynamics 365-web-API'en giver dine programmer mulighed for på kørselstidspunktet at bestemme de organisationer, også kaldet forekomster, som den bruger, der er logget på, tilhører. Du kan hente detaljerede oplysninger om disse forekomster som f.eks. URL-adressen på forekomsttjenesten, Dynamics 365-versionen, forekomst-id og andet. Du kan bruge $filter- og $select-standardparametre til en web-API-serviceanmodning til at tilpasse listen over returnerede forekomstdata. Registreringstjenesten understøttes af alle typer af Dynamics 365-installationer: online, i det lokale miljø og IFD.

Klientprogrammer har muligvis adgang til en Dynamics 365-forekomst, hvor forekomsten af URL-adressen kan ændres med tiden. Når en Dynamics 365-forekomst er flyttet fra et Microsoft Dynamics 365 (online)-datacenter til et andet. Registreringstjenesten gør det muligt for klientforekomst at bevare forekomst-id eller det entydige forekomstnavn og derefter bruge registreringstjenesten til at søge efter URL-adressen til den aktuelle forekomst.

Ud over datacenterspecifikke registreringstjenester, der er tilgængelige på slutpunktet 2011 (SOAP) og via web-API'en, er der også en web-API registreringstjeneste, der kun er global, som strækker sig over alle operationelle datacentre. Du kan finde flere oplysninger om registreringstjenesten på 2011-slutpunktet under Finde URL-adressen til din organisation ved hjælp af Organisationstjeneste.

Oplysninger leveret af registreringstjenesten

Organisationsoplysningerne gemmes i Instance-objektet for registreringstjenesten. For at se, hvilken type oplysninger der er indeholdt i det pågældende objekt, kan du sende en HTTP GET-anmodning til tjenesten for én af dine forekomster.

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

I ovenstående eksempel bruges den globale registreringstjeneste i Microsoft Dynamics 365 (online) til at få organisationsoplysninger om forekomsten med et entydigt navn på "myorg". Du kan finde flere oplysninger om denne anmodning senere i dette emne.

Omfanget af de returnerede oplysninger

For den globale registreringstjeneste, Instances-objektsættet, returneres antal forekomster, som brugeren har adgang til på tværs af alle geografiske området, når der ikke anvendes filtre. De returnerede data har et omfang, som beskrevet nedenfor.

Indeholder alle forekomster i den kommercielle sky, hvor brugeren er klargjort og aktiveret, men suveræne skyforekomster ikke returneres
Omfatter ikke forekomster, hvor brugerens konto er deaktiveret
Omfatter ikke forekomster, hvor brugerne er filtreret væk på grundlag af en forekomst af en sikkerhedsgruppe
Omfatter ikke forekomster, hvor brugeren har adgang som følge af at en stedfortræderadministrator
Hvis den kaldende bruger ikke har adgang til forekomster, returnerer svaret ganske enkelt en tom liste

Sådan får du adgang til registreringstjenester

Generelt har web-API-adressen til registreringstjenesten følgende format: <service base address>/api/discovery/. Adresserne til hver type af installation er beskrevet nedenfor. Du nemt kan finde web-API-adresser og versionsnummer for din installation i Dynamics 365-webprogrammet ved at gå til Indstillinger > Tilpasning > Udviklerressourcer

Dynamics 365 (online)-registreringstjenester

Den tjenestebaserede adresse for den globale registreringstjeneste er: https://globaldisco.crm.dynamics.com/. Dette resulterer i tjenesteadressen https://globaldisco.crm.dynamics.com/api/discovery/.

Den tjenestebaserede adresse for registreringstjenesten for et datacenter er: https://disco.crm[N].dynamics.com/. Dette resulterer i registreringstjenesteadressen https://disco.crm[N].dynamics.com/api/discovery/. De enkelte datacentre har et tilknyttet N-nummer. En komplet liste over tilgængelige Microsoft Dynamics 365 (online)-datacentre og deres N-numre finder du i Download slutpunkterne ved hjælp af siden Udviklerressourcer i Microsoft Dynamics 365.

Lokal registreringstjeneste og IFD-registreringstjeneste

Tjenestens basisadresse for registreringstjenesten for en lokal installation eller en IFD-installation er: http[s]://{servername}/ eller http[s]://dev.{servername}/. Dette resulterer i tjenesteadressen http[s]://{servername}/api/discovery/ eller http[s]://dev.{servername}/api/discovery/.

Brug af registreringstjenesten

Et objektsæt, der kaldes Instances, bruges til at få oplysninger om forekomster. Du kan bruge $select og $filter med objektetsættet Forekomster til at filtrere de returnerede data. Du kan også bruge $metadata til at få metadatadokumentet for tjenesten.

Godkendelse

Microsoft Dynamics 365 (online)-web-API-forekomster af registreringstjenesten kræver godkendelse med OAuth-adgangstokens. Lokale forekomster eller IFD-forekomster af registrerings-web-API'en vedtager godkendelsesmodellen for udrulning og understøtter enten integreret Windows-godkendelse (IWA) eller OAuth-tokens fra en pålidelig tokenprovider. Godkendelse af webprogramsession understøttes ikke.

Når registreringstjenesten er konfigureret til OAuth-godkendelse, sendes der en anmodning til tjeneste-web-API'en, uden at et token udløser access en bærerudfordring med autoritet for det "almindelige" slutpunkt og ressource-id'et for tjenesten. Når en lokal installation på samme måde konfigureres for OAuth, returnerer en bærerudfordring URL-adressen for den lokale autoritet og ressource-id'et for tjenesten.

Web-API-versionsstyring

Versioner af registreringstjenesten for et datacenter eller lokale installationer/IFD-installationer understøttes og er i overensstemmelse med versionsnummerering, som bruges af organisationstjenesten. Men den globale registreringstjeneste af Microsoft Dynamics 365 (online) er ikke knyttet til versionsnummeret for Dynamics 365-udrulningen. I stedet bruger den globale tjeneste sin egen versionsnummerering. Fra og med skrivende stund er den globale registreringstjenesten af Microsoft Dynamics 365 (online) version 1.0 (v1.0). Eksempel:

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

CORS-support

Registreringstjeneste-web-API'en understøtter CORS-standarden for adgang på tværs af oprindelse på samme måde som organisationstjeneste-web-API'en. Du kan få flere oplysninger om CORS-support på siden Bruge OAuth med Cross-Origin Resource Sharing til at oprette forbindelse til et enkelt side-program til Microsoft Dynamics 365.

Eksempler

Få oplysninger om en bestemt forekomst. Hvis du udelader GUID, returneres alle forekomster, som den godkendte bruger har adgang til.

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

Du kan bruge attributten UniqueName som en alternativ nøgle.

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

Hent en liste over tilgængelige forekomster, der er filtreret efter produktionstype.

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

Hent en egenskabsværdi for en bestemt forekomst-id.

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

Microsoft Dynamics 365

Del via