Delen via

HTTP-aanvragen opstellen en fouten afhandelen

  • Artikel

 

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

U kunt met de web-API werken door HTTP-aanvragen op te stellen en te verzenden. U moet weten hoe u de juiste HTTP-headers moet instellen en fouten moet verwerken die zijn opgenomen in de respons.

In dit onderwerp

URL voor web-API en versies

HTTP-methoden

HTTP-headers

Statuscodes identificeren

Parseerfouten van de respons

URL voor web-API en versies

Om toegang te krijgen tot de web-API moet u een URL opstellen met de componenten in onderstaande tabel.

Item

Beschrijving

Protocol

Het betreffende protocol: https:// of http://.

Basis-URL

Dit is gewoonlijk de URL die u gebruikt om de webtoepassing te openen.

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

  • Voor Internet Facing Deployment (IFD): gebruik de betreffende URL voor uw exemplaar. Deze wordt: <organization name>.<domain name>.

  • Voor Dynamics 365 (on-premises): gebruik <server name>/<organization name>

Pad van web-API

Het pad naar de web-API is: /api/data/.

Versie

De versie wordt uitgedrukt op deze manier: v[Major_version].[Minor_version][PatchVersion]/. Geldige versies voor deze release zijn:

  • v8.0/ voor Update 0.1 voor Microsoft Dynamics CRM Online 2016 en Update 0.1 voor Microsoft Dynamics CRM 2016

  • v8.1/ voor Update 1 voor Microsoft Dynamics CRM Online 2016 en Microsoft Dynamics CRM 2016 Service Pack 1

  • v8.2/ voor Update voor Dynamics 365 (online en on-premises) - december 2016

De specifieke waarde die u gebruikt, is niet belangrijk voor deze release. De bijbehorende updates of servicepacks moeten wel zijn toegepast. Meer info: Versiecompatibiliteit

Resource

De naam van de entiteit, functie of actie die u wilt gebruiken.

De URL die u gebruikt, zal bestaan uit deze onderdelen: protocol + basis-URL + pad van web-API + versie + resource.

Versiecompatibiliteit

In deze release hebben we een aantal additieve wijzigingen toegepast voor alle updates en servicepacks. Wanneer deze updates zijn toegepast, zijn dezelfde mogelijkheden toegevoegd aan daaropvolgende secundaire versies. Als u versie 8.2 kunt gebruiken, beschikken versies 8.1 en 8.0 daarom over dezelfde mogelijkheden. Dit is mogelijk omdat alle wijzigingen additief zijn of bugfixes zijn voor de items vermeld in Beperkingen van Web-API van Microsoft Dynamics 365. Er zijn geen grote wijzigingen geïmplementeerd.

Notitie

De volgende primaire versie (v9) introduceert mogelijkheden die alleen beschikbaar zijn wanneer u die versie gebruikt. Daaropvolgende secundaire versies kunnen extra mogelijkheden bevatten die niet worden toegepast in eerdere secundaire versies. De code die u hebt geschreven voor v8.x werkt nog steeds in v9.x wanneer u in de URL die u gebruikt, verwijst naar v8.2.

Voor de v8.x-release gebruikt u de recentste versie die u hebt. Updates of servicepacks in deze primaire versie bevatten geen grote wijzigingen. Dit verandert echter in toekomstige releases. U moet dan beter letten op de versie van de service waarop u zich richt.

HTTP-methoden

Voor HTTP-aanvragen kunnen een groot aantal verschillende methoden worden toegepast. Wanneer u de web-API gebruikt, kunt u alleen de methoden gebruiken die in de volgende tabel worden vermeld.

Methode

Gebruik

GET

Gebruik bij het ophalen van gegevens, inclusief het aanroepen van functies. De verwachte statuscode voor succesvol ophalen is 200 OK.

POST

Gebruik bij het maken van entiteiten of het aanroepen van acties.

PATCH

Gebruik bij het bijwerken van entiteiten of het uitvoeren van upsert-bewerkingen.

DELETE

Gebruik bij het verwijderen van entiteiten of afzonderlijke eigenschappen van entiteiten.

PUT

Gebruik in beperkte situaties om afzonderlijke eigenschappen van entiteiten bij te werken. Deze methode wordt niet aanbevolen bij het bijwerken van de meeste entiteiten. U gebruikt het bij het bijwerken van modelentiteiten.

HTTP-headers

Hoewel het OData-protocol zowel de JSON- als de ATOM-indeling toestaat, ondersteunt de web-API alleen JSON. De volgende headers kunnen daarom worden toegepast.

Elke aanvraag moet de Accept-headerwaarde van application/json bevatten, zelfs wanneer geen responstekst wordt verwacht. Elke fout die wordt geretourneerd in de respons, wordt geretourneerd als JSON. Hoewel uw code ook werkt als deze header niet is opgenomen, verdient het aanbeveling om dit toch te doen

De huidige OData-versie is 4.0, maar toekomstige versies kunnen nieuwe mogelijkheden bieden. Om te zorgen dat het duidelijk is welke OData-versie op dat moment in de toekomst wordt toegepast op uw code, moet u altijd een expliciete verklaring opnemen van de huidige OData-versie en de maximale versie die in uw code wordt toegepast. Gebruik zowel OData-Version- als OData-MaxVersion-headers ingesteld op een waarde van 4.0.

Alle HTTP-headers moeten minimaal de volgende headers bevatten.

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

Elke aanvraag die JSON-gegevens in de aanvraagtekst bevat, moet een Content-Type-header met een waarde van application/json bevatten.

Content-Type: application/json

U kunt extra headers gebruiken om specifieke mogelijkheden in te schakelen.

  • Als u gegevens wilt laten retourneren voor Create- (POST) of Update-bewerkingen (PATCH) voor entiteiten, neemt u de voorkeur return=representation op. Wanneer deze voorkeur wordt toegepast op een POST-aanvraag, heeft een Geslaagd-respons de status 201 (Created). Voor een PATCH-aanvraag heeft een Geslaagd-respons de status 200 (OK). Als deze voorkeur niet is toegepast, retourneren beide bewerkingen de status 204 (No Content). Dit geeft aan dat standaard geen gegevens worden geretourneerd in de hoofdtekst van de respons.

    Notitie

    Deze mogelijkheid is toegevoegd in de Update voor Dynamics 365 (online en on-premises) - december 2016.

  • Als u de opgemaakte waarden met een query wilt retourneren, neemt u de voorkeur odata.include-annotations op ingesteld op Microsoft.Dynamics.CRM.formattedvalue met behulp van de header Prefer.Meer informatie:Opgemaakte waarden ophalen

  • U kunt ook de header Prefer met de optie odata.maxpagesize gebruiken om op te geven hoeveel pagina's u wilt retourneren.Meer informatie:Geef het aantal entiteiten op dat op een pagina moet worden weergegeven

  • Wanneer een andere gebruiker moet worden geïmiteerd wanneer de aanroeper de bevoegdheden hiervoor heeft, voegt u de header MSCRMCallerID met de waarde systemuserid toe van de gebruiker die wordt geïmiteerd.Meer informatie:Zich als een andere gebruiker voordoen die de Web API gebruikt.

  • Als u optimistische gelijktijdigheid wilt toepassen, kunt u de header If-Match toepassen met de waarde Etag.Meer informatie:Optimistisch gelijktijdigheid toepassen.

  • Als u duplicaatdetectie wilt inschakelen voor een POST-aanvraag, kunt u de header MSCRM.SuppressDuplicateDetection: false gebruiken.Meer informatie:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

  • Als u wilt bepalen of een upsert-bewerking daadwerkelijk een entiteit moet maken of bijwerken, kunt u ook de headers If-Match en If-None-Match gebruiken.Meer informatie:Upsert toepassen op een entiteit.

  • Als u batchbewerkingen uitvoert, moet u een aantal verschillende headers in de aanvraag toepassen en met elk deel dat in de hoofdtekst wordt verzonden.Meer informatie:Batchbewerkingen uitvoeren met de Web API.

Statuscodes identificeren

Ongeacht of een HTTP-aanvraag slaagt of mislukt, bevat de respons een statuscode. Hierna volgen statuscodes die door de web-API van Microsoft Dynamics 365 worden geretourneerd.

Code

Beschrijving

Type

200 OK

U kunt dit verwachten als uw bewerking gegevens retourneert in de responstekst.

Succes

201 Created

Dit kunt u verwachten als de POST-bewerking voor uw entiteit is geslaagd en u de voorkeur return-representation in uw aanvraag hebt opgegeven.

Notitie

Deze mogelijkheid is toegevoegd in de Update voor Dynamics 365 (online en on-premises) - december 2016.

Succes

204 No Content

U kunt dit verwachten als uw bewerking is geslaagd, maar geen gegevens retourneert in de responstekst.

Geslaagd

304 Not Modified

U kunt dit verwachten als u test of een entiteit is gewijzigd sinds deze de laatste keer is opgehaald.Meer informatie:Voorwaardelijk ophalen

Omleiding

403 Forbidden

U kunt dit verwachten voor de volgende fouttypen:

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

Clientfout

401 Unauthorized

U kunt dit verwachten voor de volgende fouttypen:

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

Clientfout

413 Payload Too Large

Verwacht dit als de aanvraaglengte te groot is.

Clientfout

400 BadRequest

Verwacht dit als een argument ongeldig is.

Clientfout

404 Not Found

Verwacht dit als de resource niet bestaat.

Clientfout

405 Method Not Allowed

Deze fout treedt op voor onjuiste combinaties van methode en resource. U kunt bijvoorbeeld niet DELETE of PATCH gebruiken voor een verzameling van entiteiten.

U kunt dit verwachten voor de volgende fouttypen:

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

Clientfout

412 Precondition Failed

U kunt dit verwachten voor de volgende fouttypen:

  • ConcurrencyVersionMismatch

  • DuplicateRecord

Clientfout

500 Internal Server Error

U kunt dit verwachten wanneer een POST-aanvraag om een entiteit te maken duplicaatdetectie inschakelt en de entiteit die moet worden gemaakt een duplicaat zou zijn.Meer informatie:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

Serverfout

501 Not Implemented

Verwacht dit als een aangevraagde bewerking niet is geïmplementeerd.

Serverfout

503 Service Unavailable

Verwacht dit als de web-API-service niet beschikbaar is.

Serverfout

Parseerfouten van de respons

Details over fouten zijn opgenomen als JSON in de respons. Fouten staan in deze indeling.

 { "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>" } } }

Zie ook

Bewerkingen uitvoeren met de web-API
Querygegevens met behulp van de web-API
Een entiteit maken met de web-API
Een entiteit ophalen met de web-API
Entiteiten bijwerken en verwijderen met de Web-API
Entiteiten koppelen en ontkoppelen met de web-API
Web-API-functies gebruiken
Web-API-acties gebruiken
Batchbewerkingen uitvoeren met de Web API
Zich als een andere gebruiker voordoen die de Web API gebruikt
Voorwaardelijke bewerkingen uitvoer met de web-API

Microsoft Dynamics 365

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht