Del via

Web-API-typer og -handlinger

  • Artikel

 

Udgivet: januar 2017

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

Når du vil bruge Web-API'en, skal du finde oplysninger om, hvilke relevante funktioner der er tilgængelige. Tjenesten beskriver sig selv via tjeneste- og metadatadokumenter, som du kan få adgang til. I dette emne introducerer vi nogle vigtige begreber og beskriver, hvordan du kan finde de oplysninger, du har brug for, ved hjælp af dokumentation, der er genereret ud fra tjeneste- og metadatadokumenterne, samt dokumentationen til systemets enhedstyper, funktioner og handlinger.

Dette emne indeholder

Terminologi

Tjenestedokumenter

Objekttyper

Egenskaber

Navigationsegenskaber

Handlinger

Funktioner

Komplekse typer

Optællingstyper

Terminologi

Web-API'en implementeres ved hjælp af OData v4-standarden, som bruger et bestemt sæt udtryk, du skal være bekendt med.EDM (Entity Data Model) er den abstrakte datamodel, der bruges til at beskrive de data, der vises af OData-tjenesten. Følgende tabel indeholder en liste med ord, der er defineret i OData version 4.0 del 1: Protocol Plus Errata 02, som du skal forstå.

Udtryk

Definition

Objekttyper

Navngivne strukturerede typer med en nøgle. De definerer de navngivne egenskaber og relationer for et objekt. Enhedstyper kan afledes ved enkelt arv fra andre objekttyper.

Objekter

Forekomster af enhedstyper (f.eks. account, opportunity).

Objektsæt

Navngivne samlinger af objekter (f.eks. er accounts et objektsæt, der indeholder account objekter). Et objekts nøgle identificerer entydigt objektet inden for objektsættet.

Komplekse typer

Navngivne strukturerede typer uden nøgler, der består af et sæt egenskaber. Komplekse typer bruges ofte som egenskabsværdier i modelobjekter eller som parametre eller returværdier for handlinger.

Optællingstyper eller fastteksttyper

Navngivne primitive typer, hvis værdier er navngivne konstanter med underliggende heltalsværdier.

Funktioner

Handlinger, der ikke har bivirkninger, og som kan understøtte yderligere sammensætning, for eksempel med ekstra filtreringshandlinger eller funktioner.

Handlinger

Handlinger, der tillader bivirkninger, som f.eks. ændring af data, og som ikke kan sammensættes yderligere for at undgå en ikke-deterministisk funktionsmåde

Tjenestedokumenter

Der er to tjenestedokumenter, kan du referere til for at få flere oplysninger om Web-API'en.

Tjenestedokument

Følgende forespørgsel indtastet i adressefeltet i din browser returnerer servicedokumentet, som er en komplet liste over alle de objektsæt, der er tilgængelige for din organisation. Bemærk, at [organization URI] repræsenterer din organisations URL-adresse.


[Organization URI]/api/data/v8.2

Objektsættene returneres i form af en JSON-matrix. Hvert element i matricen har tre egenskaber, som anført i denne tabel.

Egenskab

Beskrivelse

name

Dette er navnet på objektsættet. Disse data er fra egenskaben EntityMetadata EntityType EntitySetName for objektet.

kind

For Web-API'en er kun objektsæt angivet.

url

Denne værdi er den samme som name-egenskaben, og den repræsenterer den del af ressourcestien, der henter data til objektet.

Disse oplysninger kan hentes ved hjælp af en GET-anmodning, og det kan være nyttigt at hente en liste over alle objektsæt, der er tilgængelige ved hjælp af tjenesten.

CSDL-metadatadokument

En GET-anmodning til følgende URL returnerer et forholdsvis stort (mere end 3,5 MB) CSDL-dokument (Common Schema Definition Language) eller metadatadokument, der beskriver de data og handlinger vises af tjenesten.


[Organization URI]/api/data/v8.2/$metadata

Dette dokument kan bruges som en datakilde til at generere klasser, der giver typesikre objekter for tjenesten. Men hvis du ikke bruger genererede klasser, kan du gennemgå dokumentation, der er genereret ud fra disse oplysninger i stedet.Web API Reference bruger oplysninger primært fra dette dokument, der er taget fra et ikke-tilpasset system.

Du kan få mere at vide om dette dokument i OData version 4.0 del 3: Common Schema Definition Language (CSDL) Plus Errata 02.

Tip

Før du læser resten af dette emne, skal du downloade CSDL til din organisation og kigge på, hvordan de typer, funktioner og handlinger, der er beskrevet, er inkluderet i CSDL og den understøttende dokumentation.

Objekttyper

Web API EntityType Reference viser hver af systemobjekttyperne via Web-API'en, som gemmer forretningsdata. En objekttype er en navngivet struktureret type med en nøgle. Den definerer de navngivne egenskaber og relationer for et objekt. Enhedstyper kan afledes ved enkelt arv fra andre objekttyper.Web API Metadata EntityType Reference viser en liste over hver af objekttyperne, der bruges til at styre systemets metadata. Begge er objekttyper, men du arbejder med dem på forskellige måder. Du kan finde oplysninger om brugen af modelobjekter under Bruge Web API med Dynamics 365-metadata. Hver objekttype er en del af et EntityType-element i CSDL'et. Følgende er definitionen af account EntityType fra CSDL, hvor egenskaber og navigationsegenskaber er fjernet.

<EntityType Name="account" BaseType="mscrm.crmbaseentity">
  <Key>
    <PropertyRef Name="accountid" />
  </Key>
  <!--Properties and navigation properties removed for brevity-->
  <Annotation Term="Org.OData.Core.V1.Description" String="Business that represents a customer or potential customer. The company that is billed in business transactions." />
</EntityType>

Hver EntityType-referenceside i SDK-dokumentationen bruger oplysninger fra CSDL eller metadata til at vise følgende oplysninger, når de er tilgængelige.

Oplysninger

Beskrivelse

Beskrivelse

En beskrivelse af objektet.

EntityMetadata EntityType-oplysningerne for Description-egenskaben er inkluderet i EntityType-elementet ved hjælp af Annotation-elementet, som bruger Term-attributværdien Org.OData.Core.V1.Description.

Samlings-URL-adresse

URL-adressen, der giver adgang til samlingen af hver type.

EntityMetadata EntityType-oplysningerne for EntitySetName-egenskaben indgår i CSDL-EntityContainer-elementet.Name-attributten for hvert EntitySet-element styrer, hvordan der opnås adgang til dataene via URL-adressen.

Basistype

Dette er den objekttype, som objekttypen arver fra.

BaseType-attributten for EntityType-elementet indeholder navnet på objekttypen. Dette navn har et foranstillet alias for Microsoft.Dynamics.CRM-navneområdet: mscrm.Flere oplysninger:Nedarvning af type

Vist navn

Disse oplysninger er ikke i CSDL. De hentes fra DisplayName-egenskaben EntityMetadata EntityType.

Primær nøgle

Den egenskabsværdi, der indeholder det entydige id, der bruges til at referere til en forekomst af et objekt.

PrimaryIdAttribute-egenskabsværdien EntityMetadata EntityType indgår i EntityType Key-elementet. De enkelte objekter kan have én primær nøgle.

Alternative nøgler er ikke angivet her.Flere oplysninger:Alternative nøgler

Primær attribut

Mange objekter kræver, at der angives en primær attributværdi, så denne indstilling er medtaget for nemheds skyld.

Disse oplysninger er ikke i CSDL. De hentes fra metadataene i PrimaryNameAttribute-egenskabens EntityMetadata EntityType.

Egenskaber

Se Egenskaber.

Navigationsegenskaber med enkeltværdi

Se Navigationsegenskaber med enkeltværdi.

Navigationsegenskaber med gruppeværdi

Se Navigationsegenskaber med gruppeværdi.

Handlinger, der er bundet til objekttypen

Når en handling er bundet til en bestemt objekttype, er den angivet af praktiske årsager.

Handlinger, der bruger objekttypen

Denne liste viser alle handlinger, der kan bruge objekttypen. Dette er afledt ved at indsamle referencer til alle handlinger, der refererer til den aktuelle type i parametrene eller som en returværdi.

Objekttyper, som arver fra objekttypen

Denne liste indeholder alle objekttyper, der arver direkte fra objekttypen. Du kan finde flere oplysninger under Nedarvning af type.

Ændre navnet på et objektsæt

Som standard svarer navnet på objektsættet til egenskabsværdien EntityMetadata EntityType LogicalCollectionName (EntityMetadataLogicalCollectionName). Hvis du har et brugerdefineret objekt, du vil adressere ved hjælp af et andet objektsætnavn, kan du opdatere EntityMetadata EntityType EntitySetName (EntityMetadata.EntitySetName)-egenskabsværdien for at bruge et andet navn.

Alternative nøgler

Selvom Microsoft Dynamics 365 giver mulighed for til at oprette alternative nøgler, findes kun den primære nøgle i Microsoft Dynamics 365-SDK-dokumentationen.

Ingen systemobjekter har definerede alternative nøgler. Hvis du definerer alternative nøgler for et objekt, medtages de i CSDL EntityType-elementet som en Annotation som følgende:

<Annotation Term="OData.Community.Keys.V1.AlternateKeys">
  <Collection>
    <Record Type="OData.Community.Keys.V1.AlternateKey">
      <PropertyValue Property="Key">
        <Collection>
          <Record Type="OData.Community.Keys.V1.PropertyRef">
            <PropertyValue Property="Alias" String="key name" />
            <PropertyValue Property="Name" PropertyPath="key name" />
          </Record>
        </Collection>
      </PropertyValue>
    </Record>
  </Collection>
</Annotation>

Oplysninger om alternative nøgler kan også hentes fra metadataene ved hjælp af EntityMetadata EntityType Keys-navigationsegenskaben med gruppeværdi ved at bruge Web-API'en eller EntityMetadata.Keys-egenskaben ved hjælp af organisationstjenesten.

Nedarvning af type

Arv giver mulighed for deling af fælles egenskaber og kategorisering af objekttyper i grupper. Alle objekttyper i Web API'en arver fra to af følgende objekttyper. Alle forretningsobjekttyper arver fra crmbaseentity EntityType, og alle modelobjekter arver fra crmmodelbaseentity EntityType.

Basisobjekt

Beskrivelse

crmbaseentity EntityType

Alle forretningsobjekter arver fra dette objekt. Det har ingen egenskaber. Det fungerer bare som et abstrakt basisobjekt.

activitypointer EntityType

Alle aktivitetsobjekter arver fra dette objekt. Det definerer det fælles sæt af egenskaber og navigationsegenskaber for aktivitetsobjekter.

principal EntityType

systemuser EntityType og team EntityType arver en fælles ownerid-egenskab fra dette objekt.

crmmodelbaseentity EntityType

Kun MetadataBase EntityType arver direkte fra dette objekt. Det har ingen egenskaber. Det fungerer bare som et abstrakt basisobjekt.

MetadataBase EntityType

Alle modelobjekter arver fra dette objekt. Det leverer MetadataId- og HasChanged-egenskaberne for alle objekter i modellen.

AttributeMetadata EntityType

Alle modelobjekter, der repræsenterer forskellige typer attributter, arver fra dette objekt.

EnumAttributeMetadata EntityType

Disse modelobjekter, der repræsenterer attributter, der indeholder et sæt indstillinger, arver fra dette objekt.

OptionSetMetadataBase EntityType

Denne modelobjekttype indeholder et fælles sæt egenskaber, der bruges af de BooleanOptionSetMetadata EntityType- og OptionSetMetadata EntityType-modelobjekttyper, der arver fra den.

RelationshipMetadataBase EntityType

Denne objekttype indeholder et fælles sæt egenskaber, der bruges af de ManyToManyRelationshipMetadata EntityType- ogOneToManyRelationshipMetadata EntityType-modelobjekttyper, der arver fra den.

Egenskaber

Hver objekttype kan har erklærede egenskaber, der svarer til attributter. I Web API EntityType Reference- og Web API Metadata EntityType Reference-indhold er egenskaber, der er nedarvet fra en basisobjekttype, samlet på listen over angivne egenskaber for hver objekttype. Arven forklares i beskrivelsen af hver egenskab.

I CSDL EntityType-elementerne er hver egenskab inkluderet i et Property-element med en Name-attributværdi, der svarer til de egenskaber, du angiver i kode.Type-attributværdien angiver egenskabens datatype. Egenskaber for forretningsobjekttyper bruger generelt primitive OData-typer.

Følgende er et eksempel på name-egenskaben account EntityType defineret i CSDL'et.

<Property Name="name" Type="Edm.String" Unicode="false">
  <Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>

Beskrivelsen af egenskaben er tilgængelig i et Annotation-element med Term-attributegenskaben Org.OData.Core.V1.Description. Denne beskrivelse er taget fra egenskabsværdien AttributeMetadata EntityType Description. Ikke alle egenskaber indeholder en beskrivelse.

Hver egenskab kan beregnes. Det betyder, at værdien kan fastsættes af systemet. Dette er angivet i et Annotation-element med Term-attributværdien Org.OData.Core.V1.Computed.

Hver egenskab kan også have begrænsninger for, om den kan opdateres. Dette er defineret i et Annotation-element med Term-attributværdien Org.OData.Core.V1.Permissions. Den eneste grupperede indstilling for dette er Org.OData.Core.V1.PermissionType/Read, hvilket angiver, at egenskaben er skrivebeskyttet.

Primitive typer

OData understøtter et bredt udvalg af datatyper, men Microsoft Dynamics 365 bruger ikke dem alle. I følgende tabel beskrives, hvordan Dynamics 365-organisationstjenestetyper er knyttet til primitive OData-typer.

Organisationstjenestetype

Web-API-type

Beskrivelse

BigInt

Edm.Int64

64-bit heltal med fortegn

Boolean

Edm.Boolean

Logik med binær værdi

CalendarRules

Navigationsegenskaber med enkeltværdi

Specifikke navigationsegenskaber med enkeltværdi til calendarrule EntityType.

Kunde

Navigationsegenskaber med enkeltværdi

Kunden for et objekt med denne type egenskab kan være en navigationsegenskabssæt med enkeltværdi, som er indstillet til en account- eller contact-objekttype ved hjælp af de respektive navigationsegenskaber med enkeltværdi. Når en af de respektive samlingsegenskaber med enkeltværdi indstilles, fjernes den anden.

DateTime

Edm.DateTimeOffset

Datoen og klokkeslættet med en tidszoneforskydning, ingen skudsekunder
Der er ingen DateTime-type i OData.

Decimal

Edm.Decimal

Numeriske værdier med fast præcision og skala

Dobbelt

Edm.Double

IEEE-754 binary64 flydende tal (15-17 decimaler)

EntityName

Edm.String

Sekvens af UTF-8-tegn

Billede

Edm.Binary

Binære data

Heltal

Edm.Int32

32-bit heltal med fortegn

Opslag

Navigationsegenskab med enkeltværdi

En reference til et bestemt objekt

ManagedProperty

Ikke tilgængelig

Kun til intern brug.

Notat

Edm.String

Sekvens af UTF-8-tegn

Penge

Edm.Decimal

Numeriske værdier med fast præcision og skala

Ejer

Navigationsegenskab med enkeltværdi

En reference til principal EntityType. Både systemuser- og team-enhedstypen arver deres ownerid-egenskab fra prinicipal-objekttypen.

Deltagerliste

Navigationsegenskab med gruppeværdi til activityparty-objekttypen.

Egenskaben activitypartyparticipationtypemask indeholder en værdi, der repræsenterer deltagerens rolle. Du kan finde flere oplysninger under Typer af aktivitetsparter.

Valglisteattributter

Edm.Int32

32-bit heltal med fortegn

Område

Edm.Int32

32-bit heltal med fortegn

Status

Edm.Int32

32-bit heltal med fortegn

Streng

Edm.String

Sekvens af UTF-8-tegn

Uniqueidentifier

Edm.Guid

16-byte (128-bit) entydigt id

Opslagsegenskaber

For de fleste navigationsegenskaber med enkeltværdi finder du en beregnet, skrivebeskyttet egenskab, der bruger følgende navngivningskonvention: _<name>_value, hvor <name> svarer til navnet på navigationsegenskaben med enkeltværdi. Undtagelsen til dette mønster er, når en opslagsattribut for objektet kan acceptere flere typer objektreferencer. Et almindeligt eksempel er, hvordan incident-objektets customerid-attribut kan indstilles til en reference, der er enten et contact- eller account-objekt. I incident EntityTypeSingle-valued navigation properties finder du customerid_account og customerid_contact som separate navigationsegenskaber med enkeltværdi, som skal afspejle den kunde, der er knyttet til en salgsmulighed. Hvis du angiver en af disse navigationsegenskaber med enkeltværdi, indstilles den anden til null, fordi begge er bundet til customerid-attributten. I incident EntityTypeProperties finder du en _customerid_value-opslagsegenskab, der indeholder den samme værdi som den, der er angivet for den af navigationsegenskaberne med enkeltværdi, der indeholder en værdi.

Generelt bør du undgå at bruge opslagsegenskaber og i stedet bruge de tilsvarende navigationsegenskaber med enkeltværdi. Disse egenskaber er blevet medtaget, fordi de kan være nyttige i visse integrationssammenhænge. Disse egenskaber er skrivebeskyttede og beregnes, fordi de ganske enkelt vil afspejle de ændringer, der anvendes ved hjælp af den tilsvarende navigationsegenskab med enkeltværdi.

Når du medtager opslagsegenskaber i en forespørgsel, kan du anmode om, at der skal indgå anmærkninger, der indeholder yderligere oplysninger om de data, der er angivet for de underliggende attributter, som ikke er repræsenteret ved en navigationsegenskab med enkeltværdi.Flere oplysninger:Hente data om egenskaber for opslag

I OData giver navigationsegenskaberne dig adgang til data, der er relateret til det aktuelle objekt. Når du henter et objekt, kan du vælge at udvide navigationsegenskaberne, så de omfatter de relaterede data. Der er to typer navigationsegenskaber: med enkeltværdi og med gruppeværdi.

Navigationsegenskaberne svarer til opslagsattributter, der understøtter mange til en-relationer og gør det muligt at indstille en reference til et andet objekt. I CSDL EntityType-elementet defineres de som et NavigationProperty-element med en Type-attribut, der er indstillet til en enkelt type. Følgende er et eksempel på account EntityType createdby-navigationsegenskaben med enkeltværdi i CSDL'et:

<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
 <ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>

Hver navigationsegenskab, der repræsenterer en navigationsegenskab med enkeltværdi har en tilsvarende navigationsegenskab med gruppeværdi, der er angivet af Partner-attributværdien. Hver navigationsegenskab med enkeltværdi har også et ReferentialConstraint-element med en Property-attributværdi, der repræsenterer den beregnede skrivebeskyttede opslagsegenskab, der kan bruges til at hente den tilsvarende GUID-værdi for det relaterede objekt.Flere oplysninger:Opslagsegenskaber

Disse egenskaber svarer til en til mange- eller mange til mange-relationer. I CSDL EntityType-elementet defineres de som et NavigationProperty-element med en Type-attribut, der er indstillet til en gruppe af en type. Følgende repræsenterer den account EntityType Account_Tasks-navigationsegenskaben med gruppeværdi, som repræsenterer en en til mange-relation:

<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />

Når navigationsegenskaben med gruppeværdi repræsenterer en mange til mange-relation, er navnet på navigationsegenskaben og partnerens navn det samme. Følgende repræsenterer account EntityType accountleads_association-navigationsegenskaben med gruppeværdi, som repræsenterer en mange til mange-relation:

<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />

Forskellen mellem en til mange- og mange til mange-relationer er ikke vigtig, når du bruger Web-API'en. Den måde, du knytter objekter til hinanden, er den samme uanset type af relation. Selvom mange til mange-relationer stadig bruger overlappende objekter i baggrunden, er det kun nogle få særlige systemoverlappende objekter, der medtages i Web API EntityType Reference. For eksempel er campaignactivityitem EntityType teknisk set et overlappende objekt, men det er medtaget, fordi det har flere egenskaber end et almindeligt overlappende objekt.

Et almindeligt overlappende objekt har kun de fire grundlæggende egenskaber, der skal til for at kunne vedligeholde mange til mange-relationen. Når du opretter en brugerdefineret mange til mange-relation mellem objekter, oprettes et almindeligt overlappende objekt for at understøtte relationen. Da du skal bruge navigationsegenskaber til at udføre handlinger, der involverer mange til mange-relationer, dokumenteres almindelige overlappende objekter ikke, men de er stadig tilgængelige ved hjælp af Web-API'en. Disse overlappende objekttyper er tilgængelige ved hjælp af navnet på et objektsæt, der bruger følgende navngivningskonvention: <overlappende objekts logiske navn>+ 'collection'. Eksempelvis kan du hente oplysninger fra det overlappende contactleads-objekt ved hjælp af [Organization URI]/api/data/v8.2/contactleadscollection. Du bør kun bruge disse almindelige overlappende objekter i situationer, hvor du vil anvende sporing af ændringer.

Handlinger

Handlinger er handlinger, der tillader bivirkninger, som f.eks. ændring af data, og som ikke kan sammensættes yderligere for at undgå en ikke-deterministisk funktionsmåde

I emnet Web API Action Reference kan du se en liste over alle tilgængelige systemhandlinger.Flere oplysninger:Brug Web API-handlinger.

Funktioner

Funktioner er handlinger, der ikke har bivirkninger, og som kan understøtte yderligere sammensætning, for eksempel med ekstra filtreringshandlinger eller funktioner.

Der findes to funktionstyper defineret i Web-API'en:

Flere oplysninger:Bruge Web-API-funktioner

Komplekse typer

Komplekse typer er navngivne strukturerede typer uden nøgler, der består af et sæt egenskaber. Komplekse typer bruges ofte som egenskabsværdier i modelobjekter eller som parametre eller returværdier for handlinger.

Web API ComplexType Reference viser en liste over alle systemets komplekse typer.Komplekse typer er navngivne strukturerede typer uden nøgler, der består af et sæt egenskaber. De bruges ofte som egenskabsværdier i modelobjekter eller som parametre eller returværdier for handlinger. Følgende er WhoAmIResponse ComplexType fra CSDL.

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

Optællingstyper

Optællingstyper eller fastteksttyper er navngivne primitive typer, hvis værdier er navngivne konstanter med underliggende heltalsværdier.

Web API EnumType Reference viser en liste over alle systemets fastteksttyper.Optællingstyper er navngivne primitive typer, hvis værdier er navngivne konstanter med underliggende heltalsværdier. Følgende er AccessRights EnumType fra CSDL.

<EnumType Name="AccessRights">
  <Member Name="None" Value="0" />
  <Member Name="ReadAccess" Value="1" />
  <Member Name="WriteAccess" Value="2" />
  <Member Name="AppendAccess" Value="4" />
  <Member Name="AppendToAccess" Value="16" />
  <Member Name="CreateAccess" Value="32" />
  <Member Name="DeleteAccess" Value="65536" />
  <Member Name="ShareAccess" Value="262144" />
  <Member Name="AssignAccess" Value="524288" />
</EnumType>

Se også

Brug Microsoft Dynamics 365 Web API
Godkende Microsoft Dynamics 365 med Web-API'en
Udføre operationer ved hjælp af web-API

Microsoft Dynamics 365

© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret