Del via

Skrive HTTP-anmodninger og håndtere fejl

  • Artikel

 

Udgivet: januar 2017

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

Du interagerer med Web-API'en ved at oprette og sende HTTP-anmodninger. Du har brug at vide, hvordan du angiver de relevante HTTP-headere og håndterer eventuelle fejl, der er inkluderet i svaret.

Dette emne indeholder

URL-adressen til Web-API og versioner

HTTP-metoder

HTTP-headere

Identificere statuskoder

Fejlmeddelelse fra svaret under opdeling af tekst

URL-adressen til Web-API og versioner

Du skal oprette en URL-adresse ved hjælp af komponenterne i tabellen nedenfor for at få adgang til Web-API'en.

Element

Beskrivelse

Protokol

Den relevante protokol, enten https:// eller http://.

Basis-URL-adresse

Dette er den URL-adresse, du normalt bruger til at åbne webprogrammet.

  • For Microsoft Dynamics 365 (online): Brug <tenant name>.crm.dynamics.com.

  • For Installation med adgang via internet: Brug den relevante URL-adresse til din forekomst. Det er: <organization name>.<domain name>.

  • For Dynamics 365 (i det lokale miljø): Brug <server name>/<organization name>

Sti til Web-API

Stien til Web-API'en er /api/data/.

Version

Versionen er angivet på denne måde: v[Major_version].[Minor_version][PatchVersion]/. Gyldige versioner til denne version er:

  • v8.0/ For Opdatering 0.1 til Microsoft Dynamics CRM Online 2016 og Opdatering 0.1 til Microsoft Dynamics CRM 2016

  • v8.1/ For Opdatering 1 til Microsoft Dynamics CRM Online 2016 og Microsoft Dynamics CRM 2016 Service Pack 1

  • v8.2/ til December 2016 – opdatering til Dynamics 365 (online og det lokale miljø)

Det er ikke vigtigt, hvilken værdi du bruger i denne version, så længe du har anvendt de tilsvarende opdateringer eller servicepakker. Flere oplysninger: Versionskompatibilitet

Ressource

Navnet på det objekt, den funktion eller handling, du vil bruge.

Den URL-adresse, du skal bruge, består med følgende dele: protokollen + basis-URL-adressen + stien til Web-API + version + ressource.

Versionskompatibilitet

Vi har anvendt en række additive ændringer i de enkelte opdateringer eller servicepakker i denne version. Når disse opdateringer er anvendt, har de føjet de samme funktioner til efterfølgende underordnede versioner. Derfor, hvis du kan bruge version 8.2, har version 8.1 og 8.0 de samme funktioner. Dette er muligt, fordi alle ændringerne er additive eller er fejlrettelser anvendt på de elementer, der er angivet i Microsoft Dynamics 365 Web API-begrænsninger. Der blev introduceret nogen vigtige ændringer.

Bemærk

Den næste overordnede version (v9) introducerer funktioner, som kun er tilgængelige i denne version. Efterfølgende underordnede versioner kan indeholde yderligere egenskaber, som ikke bliver tilbageført til tidligere underordnede versioner. Din kode, der er skrevet til v8.x, fungerer fortsat i v9.x, når du refererer til v8.2 i den URL-adresse, du bruger.

For version v8.x skal du bruge den nyeste version, du kan – opdateringer eller servicepakker inden for denne overordnede version indeholder ingen vigtige ændringer. Men det vil ændre sig i kommende versioner, hvor skal du være mere opmærksom på versionen af den service, du adresserer.

HTTP-metoder

HTTP-anmodninger kan anvende en række forskellige metoder. Når du bruger web-API'en, bruger du kun de metoder, der er angivet i følgende tabel.

Metode

Brug

GET

Bruges til hentning af data, herunder kald af funktioner. Den forventede statuskode for en vellykket hentning er 200 OK.

POST

Bruges til oprettelse af objekter eller kald af handlinger.

PATCH

Bruges til opdatering af objekter eller udførelse af upsert-handlinger.

DELETE

Bruges til sletning af objekter eller individuelle egenskaber for objekter.

PUT

Bruges i få situationer til opdatering af individuelle egenskaber for objekter. Denne metode kan kun anbefales til opdatering af de færreste objekter. Du skal bruge metoden, når du opdaterer modelobjekter.

HTTP-headere

Selvom OData-protokollen giver mulighed for både JSON- og ATOM-format, understøtter web-API'en kun JSON. Derfor kan følgende headere anvendes.

Enhver anmodning skal indeholde Accept-headerværdien for application/json, selv når der ikke forventes en svartekst. Eventuelle fejl, der returneres i svaret, returneres som JSON. Mens koden skulle kunne fungere, selvom denne header er ikke inkluderet, anbefaler vi at inkludere den som best practice

Den aktuelle OData-version er 4.0, men fremtidige versioner kan indeholde ny funktionalitet. For at sikre, at der ikke er tvivl om den OData-version, der vil blive anvendt på din kode i fremtiden, skal du altid medtage en eksplicit erklæring af den aktuelle OData-version og den højeste version, der kan anvendes i din kode. Brug både OData-Version- og OData-MaxVersion-headere, som er indstillet til en 4.0-værdi.

Alle HTTP-headere skal mindst inkludere følgende headere.

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

Enhver anmodning, der omfatter JSON-data i anmodningsteksten skal inkludere en Content-Type-header med en application/json-værdi.

Content-Type: application/json

Du kan bruge flere headere til at aktivere bestemte funktioner.

  • Hvis du vil returnere data i forbindelse med oprettelse (POST) eller opdatering (PATCH) for objekter, skal du medtage return=representation-indstillingen. Når denne indstilling er anvendt til en POST-anmodning, vil et vellykket svar have statussen 201 (Created). For en PATCH-anmodning vil et vellykket svar have statussen 200 (OK). Uden denne indstilling vil begge handlinger returnere statussen 204 (No Content) for at afspejle, at ingen data returneres som standard i svarets brødtekst.

    Bemærk

    Denne funktion blev tilføjet med December 2016 – opdatering til Dynamics 365 (online og det lokale miljø).

  • Hvis du vil returnere formaterede værdier med en forespørgsel, skal du inkludere odata.include-annotations-præferencen indstillet til Microsoft.Dynamics.CRM.formattedvalue ved hjælp af Prefer-headeren.Flere oplysninger:Medtage formaterede værdier

  • Du kan også bruge Prefer-headeren med indstillingen odata.maxpagesize for at angive, hvor mange sider du vil returnere.Flere oplysninger:Angiv antallet af objekter, der skal returneres i en side

  • For at efterligne en anden bruger, når kaldende har rettigheder til at gøre dette, skal du tilføje MSCRMCallerID-headeren med systemuserid-værdien for den bruger, der skal efterlignes.Flere oplysninger:Efterligne en anden bruger ved hjælp af Web-API'en.

  • Hvis du vil anvende optimistisk samtidighed, kan du anvende If-Match-headeren med en Etag-værdi.Flere oplysninger:Anvend optimistisk samtidighed.

  • Hvis du vil aktivere registrering af dubletter for en POST-anmodning, du kan bruge MSCRM.SuppressDuplicateDetection: false-headeren.Flere oplysninger:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

  • Hvis du vil styre, om en upsert-handling skal oprette eller opdatere et objekt, kan du også bruge If-Match- og If-None-Match-headeren.Flere oplysninger:Brug af upsert på et objekt.

  • Når du udfører batchhandlinger, skal du anvende en række forskellige headere i anmodningen og i hver del, der sendes i brødteksten.Flere oplysninger:Udføre batchhandlinger ved hjælp af Web-API.

Identificere statuskoder

Uanset om en HTTP-anmodning lykkes eller mislykkes, vil svaret indeholde en statuskode. Statuskoder, som returneres af Microsoft Dynamics 365-Web-API'en omfatter følgende.

Kode

Beskrivelse

Type

200 OK

Forvent dette, når din handling returnerer data i svarteksten.

Fuldført

201 Created

Du kan forvente dette, når objektets POST-handling lykkes, og du har angivet return-representation-indstillingen i din anmodning.

Bemærk

Denne funktion blev tilføjet med December 2016 – opdatering til Dynamics 365 (online og det lokale miljø).

Fuldført

204 No Content

Forvent dette, når din handling lykkes, men ikke returnerer data i svarteksten.

Fuldført

304 Not Modified

Forvent dette, når du tester, om et objekt er blevet ændret, siden det sidst blev hentet.Flere oplysninger:Betingede hentninger

Omdirigering

403 Forbidden

Forvent dette for følgende typer af fejl:

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

Klientfejl

401 Unauthorized

Forvent dette for følgende typer af fejl:

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

Klientfejl

413 Payload Too Large

Forvent dette, når længden på anmodningen er for stor.

Klientfejl

400 BadRequest

Forvent dette, når et argument er ugyldigt.

Klientfejl

404 Not Found

Forvent dette, når ressourcen ikke findes.

Klientfejl

405 Method Not Allowed

Denne fejl opstår ved forkerte metode- og ressourcekombinationer. For eksempel kan du ikke bruge DELETE eller PATCH på en samling af objekter.

Forvent dette for følgende typer af fejl:

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

Klientfejl

412 Precondition Failed

Forvent dette for følgende typer af fejl:

  • ConcurrencyVersionMismatch

  • DuplicateRecord

Klientfejl

500 Internal Server Error

Forvent dette, når en POST-anmodning om at oprette et objekt muliggør registrering af dubletter og det objekt, der skal oprettes, er en dublet.Flere oplysninger:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

Serverfejl

501 Not Implemented

Forvent dette, når der er anmodet om handlinger, som ikke er blevet implementeret.

Serverfejl

503 Service Unavailable

Forvent dette, når web API-tjenesten ikke er tilgængelig.

Serverfejl

Fejlmeddelelse fra svaret under opdeling af tekst

Oplysninger om fejl er medtaget som JSON i svaret. Fejlmeddelelser vises i dette format.

{ "error":{ "code": "
        <This code is not related to the http status code and is frequently empty>", "message": "
        <A message describing the error>", "innererror": { "message": "
        <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
        <Details from the server about where the error occurred>" } } }

Se også

Udføre operationer ved hjælp af web-API
Forespørg på data ved hjælp af Web-API'en
Oprette et objekt ved hjælp af Web-API
Hente et objekt ved hjælp af web-API'et
Opdatere og slette objekter ved hjælp af web-API'et
Tilknytte og fjerne tilknytningen af objekter ved hjælp af web-API'et
Bruge Web-API-funktioner
Brug Web API-handlinger
Udføre batchhandlinger ved hjælp af Web-API
Efterligne en anden bruger ved hjælp af Web-API'en
Udfør betingede operationer ved hjælp af web-API

Microsoft Dynamics 365

© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret