Web-API-functies gebruiken
Gepubliceerd: januari 2017
Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Acties en functies staan voor herbruikbare bewerkingen die u kunt uitvoeren met de Web API. Er zijn twee typen functies in de Web API:
Functies
Gebruik een GET-aanvraag met functies die in Web API Function Reference worden vermeld, om bewerkingen uit te voeren die geen bijwerkingen hebben. Deze functies halen doorgaans gegevens op. Ze retourneren een verzameling of een complex type. Al deze functies hebben een corresponderend bericht in de organisatieservice.Queryfuncties
Gebruik de functies in Web API Query Function Reference om eigenschappen en waarden in de opbouw van een query te evalueren. Elk van deze functies heeft een overeenkomstige ConditionOperator-waarde.
In dit onderwerp
Parameters doorgeven aan een functie
Een verwijzing naar een entiteit doorgeven aan een functie
Gebonden en ongebonden functies
Een query met functies samenstellen
Parameters doorgeven aan een functie
Voor functies waarvoor parameters zijn vereist, wordt het aanbevolen om de waarden door te geven met behulp van parameters. Als u bijvoorbeeld de GetTimeZoneCodeByLocalizedName Function gebruikt, moet u de parameterwaarden LocalizedStandardName en LocaleId gebruiken. Dus u kunt de volgende inline syntaxis gebruiken zoals hier aangegeven.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)
Er is echter een onopgelost probleem bij het gebruik van DateTimeOffset-waarden met de inline syntaxis, dat wordt uitgelegd in het volgende artikel: DateTimeOffset als queryparameter #204.
Daarom wordt aanbevolen om de waarden als parameters door te geven zoals in de volgende voorbeeldcode wordt getoond. Als u deze aanbevolen werkwijze wilt gebruiken, kunt u het onopgeloste probleem dat van toepassing is op DateTimeOffset omzeilen.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033
Met parameteraliassen kunt u ook parameterwaarden hergebruiken om de totale lengte van URL in te korten wanneer de parameterwaarde wordt gebruikt.
Een verwijzing naar een entiteit doorgeven aan een functie
Voor bepaalde functies is het vereist dat een verwijzing naar een bestaande entiteit wordt doorgegeven. Bijvoorbeeld hebben de volgende functies een parameter die een crmbaseentity EntityType vereist:
Wanneer u een verwijzing naar een bestaande entiteit doorgeeft, gebruikt u de @odata.id-annotatie naar de URI voor de entiteit. Als u bijvoorbeeld de RetrievePrincipalAccess Function gebruikt, kunt u met de volgende URI toegang voor ophalen opgeven voor een specifieke contactpersoon:
GET cc_WebAPI_ServiceURI/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}
De @odata.id-annotatie kan de volledige URI zijn, maar met een relatieve Uri functioneert het ook.
Gebonden en ongebonden functies
U kunt alleen de functies in Web API Function Reference binden. Queryfuncties worden nooit gebonden
Gebonden functies
Wanneer in het d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl een Function-element een gebonden functie vertegenwoordigt, heeft het een IsBound-kenmerk bij de waarde true. Het eerste Parameter-element dat in de functie is gedefinieerd, vertegenwoordigt de entiteit waaraan de functie is gebonden. Wanneer het kenmerk Type van de parameter een verzameling is, is de functie gebonden aan een verzameling entiteiten. Hierna volgt als voorbeeld de definitie van de CalculateTotalTimeIncident Function en CalculateTotalTimeIncidentResponse ComplexType in de CSDL.
<ComplexType Name="CalculateTotalTimeIncidentResponse">
<Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
<Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
<ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>
Deze gebonden functie is vergelijkbaar met de CalculateTotalTimeIncidentRequest die door de organisatieservice wordt gebruikt. In de Web API wordt deze functie gebonden aan de incident EntityType die de eigenschap CalculateTotalTimeIncidentRequest.IncidentId vertegenwoordigt. In plaats van een CalculateTotalTimeIncidentResponse retourneert deze functie een CalculateTotalTimeIncidentResponse ComplexType. Wanneer een functie een complex type retourneert, wordt de definitie ervan direct boven de definitie van de functie in de CSDL weergegeven.
Om een gebonden functie aan te roepen, voegt u de volledige naam van de functie toe aan de URL en neemt u alle benoemde parameters op tussen de haakjes na de functienaam. De volledige functienaam bevat de naamruimte Microsoft.Dynamics.CRM. De functies die niet zijn gebonden moeten niet de volledige naam gebruiken.
Belangrijk
Een gebonden functie moet worden aangeroepen met een URI om de eerste parameterwaarde in te stellen. U kunt deze niet als een benoemde parameterwaarde instellen.
Het volgende voorbeeld toont het gebruik van de CalculateTotalTimeIncident Function die is gebonden aan de incidententiteit.
Aanvraag
GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Respons
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context":"cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30 }
Ongebonden functies
De WhoAmI Function is niet gebonden aan een entiteit. Ze is gedefinieerd in de CSDL zonder een IsBound-kenmerk.
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
<Function Name="WhoAmI">
<ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>
Deze functie komt overeen met de WhoAmIRequest en retourneert een WhoAmIResponse ComplexType die overeenkomt met de WhoAmIResponse die door de organisatieservice wordt gebruikt. Deze functie heeft geen parameters.
Wanneer u een ongebonden functie aanroept, moet u enkel de functienaam gebruiken zoals die in het volgende voorbeeld wordt weergegeven.
Aanvraag
GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Respons
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse", "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1", "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1", "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1" }
Een query met functies samenstellen
Er zijn twee manieren waarop functies kunnen worden gebruikt voor het beheer van gegevens die met query's zijn geretourneerd. Bepaalde functies staan het beheer toe over de kolommen of voorwaarden die ze hebben geretourneerd, en u gebruikt queryfuncties om voorwaarden in een query te evalueren.
Samenstelbare functies
Sommige functies die in Web API Function Reference worden genoemd, retourneren een verzameling van entiteiten. Een deel van deze functies is samenstelbaar wat betekent dat u een extra $select of $filter-systeemqueryoptie kunt opnemen om te bepalen welke kolommen er in de resultaten worden geretourneerd. Deze functies hebben een IsComposable kenmerk in de CSDL. Elk van deze functies heeft een begeleidend bericht in de organisatieservice, dat ofwel een parameter van het type ColumnSet ofwel van het type QueryBase accepteert. De systeemqueryopties OData bieden dezelfde functionaliteit, dus deze functies hebben niet dezelfde parameters als hun begeleidende berichten in de organisatieservice. In de volgende tabel ziet u een lijst van deze samenstelbare functies in deze versie.
Queryfuncties
De functies die in Web API Query Function Reference worden weergegeven, zijn bedoeld om te worden gebruikt om een query samen te stellen. Deze functies kunnen worden gebruikt op een manier die lijkt op de Standaardqueryfuncties, maar er zijn enkele belangrijke verschillen.
U moet de volledige naam van de functie gebruiken en de namen van de parameters erin opnemen Het volgende voorbeeld toont hoe u de LastXHours Function moet gebruiken om alle accountentiteiten te retourneren die de afgelopen 12 uur zijn gewijzigd.
GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12
Zie ook
Web API-functies en actievoorbeeld (C#)
Voorbeeld web-API-functies en acties (JavaScript op client)
Bewerkingen uitvoeren met de web-API
HTTP-aanvragen opstellen en fouten afhandelen
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-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