Internet API-Typen und -Vorgänge

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Um Web API zu verwenden, müssen Sie Informationen zu dem suchen, was für Sie zur Nutzung verfügbar ist. Der Dienst beschreibt sich über Service- und Metadatendokumente, auf die Sie zugreifen können. Dieses Thema enthält wichtige Konzepte und beschreibt, wie Sie die von Ihnen benötigten Informationen mithilfe von Dokumentationen finden, die aus Service- und Metadatendokumenten sowie der Dokumentation der Systementitätstypen, Funktionen und Aktionen erstellt werden.

In diesem Thema

Terminologie

Servicedokumente

Entitätstypen

Eigenschaften

Navigationseigenschaften

Aktionen

Funktionen

Komplexe Typen

Enumerationstypen

Terminologie

Der Web API wird mithilfe des ODatas v4 Standards implementiert, der bstimmte Begriffe verwendet, mit denen Sie vertraut sein müssen.Entity Data Model (EDM) ist das abstrakte Datenmodell, das verwendet wird, um die Daten zu beschreiben, die von einem OData-Service verfügbar gemacht werden. Die folgende Tabelle enthält eine ausgewählte Terminologieliste definiert in OData-Version 4.0, Teil 1 Protokoll Plus Errata 02, das Sie verstehen sollten.

Servicedokumente

Es gibt zwei Servicedokumente, auf die Sie verweisen können, um mehr über den Web API zu erfahren.

Servicedokument

Die folgende, Abfrage, die in das Adressfeld des Browsers eingegeben wird, gibt das Service-Dokumenht zurück, eine vollständige Liste aller Entitätssätze, die für Ihre Organisation verfügbar sind. Beachten Sie, dass Organisation [URI] die URL für Ihre Organisation darstellt.

[Organisations-URI]/api/data/v8.2

Die Entitätssätze werden in Form eines JSON Arrays zurückgegeben. Jedes Element im Array besteht aus drei aufgelisteten Eigenschaften aufgelistet in diesr Tabelle.

Diese Information kann mithilfe der GET Anfrage abgerufen werden und kann hilfreich sein, um eine Liste aller verfügbaren Entitätssätze, die den Service nutzen, abzurufen.

CSDL-Metadatendokument

Eine GET Anfrage für die folgende URL gibt ein eher grosses (mehr als 3.5 MB) Common Schema Definition Language (CSDL) -Dokument oder Metadaten-Dokument zurück, das die Daten und den Ablauf des Service darstellt.

[Organisations-URI]/api/data/v8.2/$metadata

Dieses Dokument kann als Datenquelle verwendet werde, um Klassen zu erstellen, die stark typisierte Objekte für den Service bereitstellen. Aber, wenn Sie keine generierten Klassen verwenden, sollten Sie die Dokumentation, die aus diesen Informationen generiert wurden, überprüfen.Web API Reference verwendet primär Informationen in diesem Dokument, die einem nicht benutzerdefinierten System entnommen wurden.

Sie erfahren mehr über dieses Dokument unter OData-Version 4.0 Teil 3: Common Schema Definition Language (CSDL) Plus Errata 02.

Entitätstypen

Web API EntityType Reference führt alle Systementitätstypen auf, die durch die Web API verfügbar sind, die Geschäftsdaten speichert. Ein Entitätstyp ist ein benannter strukturierter Typ von einen Schlüssel. Sie definieren die benannten Eigenschaften und Beziehungen einer Entität. Entitätstypen können durch einzelne Vererbung von anderen Entitätstypen abgeleitet werden.Web API Metadata EntityType Reference fürht die Entitätstypen auf, die verwendet werden, um die Systemmetadaten zu verwalten. Beides sind Entuitätstypen, aber die Art, wie Sie mit ihnen arbeiten, ist unterschiedlich. Siehe Verwenden der Web-API mit Dynamics 365-Metadaten für Informationen zur Verwendung von Modellentitäten. Jeder Entitätstyp ist in einem EntityType-Element im CSDL enthalten. Im Folgenden finden Sie die Definition des account EntityType vom CSDL mit entfernten Eigenschaften und Navigationseigenschaften.

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

Jede EntityType Referenzseite in der SDK-Dokumentation verwendet Informationen im CSDL oder Metadaten, um die folgenden Informationen anzuzeigen, falls verfügbar.

Ändern des Namens eines Entitätssets

Standardmäßig entspricht der Entitätssetname dem EntityMetadata EntityTypeLogicalCollectionName (EntityMetadataLogicalCollectionName) Eigenschaftswert. Wenn Sie eine benutzerdefinierte Entität haben, die mit einem anderen Entitätsnamen ansprechen möchten, können Sie den EntityMetadata EntityTypeEntitySetName (EntityMetadata.EntitySetName) Eigenschaftswert aktualisieren, um einen anderen Entitätsnamen zu verwenden.

Alternativschlüssel

Obwohl Microsoft Dynamics 365 die Erstellung von Alternativschlüsseln zulässt, findet man nur den Primärschlüssel in der Microsoft Dynamics 365 SDK Dokumentation.

Keine dieser Systementitäten hat definierte Alternativschlüssel. Wenn Sie Alternativschlüssel für eine Entität definieren, können sie im Element CSDL EntityType als Annotation beispielsweise folgende enthalten:

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

Informationen zu Alternativschlüssel können auch aus den Metadaten mithilfe der EntityMetadata EntityType Keys sammlungswertigen Navigationseigenschaft mithilfe des Web APO oder der EntityMetadata.Keys Eigenschaft mithilfe des Organisationsservices aberufen werden.

Typvererbung

Vererbung ist das Freigeben von allgemeinen Eigenschaften und die Kategorisieren von Entitätstypen in Gruppen. Alle Entitätstypen im Web API erben von den zwei folgenden Entitätstypen. Alle Geschäftsentitätstypen erben unter crmbaseentity EntityType und alle Modellentitäten erben von crmmodelbaseentity EntityType

Eigenschaften

Jeder Entitätstpy kann Eigenschaften haben, die den Attributen entsprechen. Im Web API EntityType Reference und Web API Metadata EntityType Reference Inhalt werden Eigenschaften, die von einem Basisentitätstyp vererbt werden, in der Liste der deklarierten Eigenschaften für jeden Entitätstyp kombiniert. Die Vererbung wird in der Beschreibung für jede ausgerufen Eigenschaft definiert.

In den CSDL EntityType Elementen ist jede Eigenschaft in einem Property-Element mit einem Name Attributwert eingeschlossen, der den Eigenschaften entspricht, die die Sie im Code festlegen. Der Type Attributwert definiert den Datentyp der Eoigenschaft. Eigenschaften für Geschäftsentitätstypen verwenden im Allgemeinen OData primitive Typen.

Nachfolgend finden Sie ein Beispiel der account EntityTypename Eigenschaft in CSDL.

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

Die Beschreibung der Eigenschaft ist in einer Annotation-Element mit der Term-Attributeigenschaft von Org.OData.Core.V1.Descriptionverfügbar. Diese Beschreibung wird vom Eigenschaftswert AttributeMetadata EntityType Description weitergeleitet. Nicht alle aufgelisteten Eigenschaften haben eine Beschreibung.

Jede Eigenschaft kann berechnet werden. Das bedeutet, dass der Wert möglicherweise vom System festgelegt ist. Dies wird in einem Annotation-Element mit dem Term Attributwert von Org.OData.Core.V1.Computedangegeben.

Jede Eigenschaft kann auch Beschränkungen haben, ob sie aktualisiert wird. Dies wird in einem Annotation-Element mit dem Term Attributwert von Org.OData.Core.V1.Permissionsangegeben. Die einzige Option dafür ist Org.OData.Core.V1.PermissionType/Read, der angibt, dass die Eigenschaft schreibgeschützt ist.

Primitive Typen

OData unterstützt eine Vielzahl von Datentypen, jedoch nicht alle Microsoft Dynamics 365 werden verwendet. Die folgende Tabelle enthält eine Beschreibung, wie Dynamics 365 Organisationsservicetypen zu OData primitiven Typen zugeordnet werden.

Such-Eigenschaften

Für die meisten einzelwertigen Navigationseigenschaften finden Sie eine berechnete, schreibgeschützte Eigenschaft, die die folgende Namenskonvention verwendet: _<name>_value wo <name> dem Namen der einzelwertigen Navigationseigenschaft entspricht. Ausnahmen zu diesem Muster bildet ein Suchattribut einer Entität, das mehrere Typen von Entitätsverweisen annehmen kann. Ein allgemeines Beispiel dafür ist dasincidentcustomeridEntitätsattribut, das als Referenz gesetzt werden kann und entweder eine contact oder account Entität ist. Im incident EntityTypeSingle-valued navigation properties finden Sie unter customerid_account und customerid_contact als separate einzelwertige Navigationseigenschaften, um den Kunden zu berücksichtigen, die der Verkaufschance zugeordnet ist. Wenn diese einzelwertige Navigationseigenschaften festgelegt ist, wird die andere auf Null gesetzt, weil sie an das customerid-Attribut gebunden sind. Im incident EntityTypeProperties finden Sie eine _customerid_value Sucheneigenschaft, die denselben Wert enthält, der für die einzelwertigen Navigationseigenschaften festgelegt ist, die einen Wert enthält.

Im Allgemeinen sollten Sie keine Sucheigenschaften verwenden und stattdessen die entsprechenden einzelwertigen Navigationseigenschaften verwenden. Diese Eigenschaften sind eingeschlossen, weil sie möglicherweise für bestimmte Integrationsszenarien hilfreich sein können. Diese Eigenschaften sind schreibgeschützt und berechnet, weil sie einfach die Änderungen wiedergeben, die mithilfe der entsprechenden einzelwertigen Navigationseigenschaft angewendet werden.

Wenn Sie Sucheneigenschaften in einer Abfrage mit einschließen, können Sie verlangen, dass Anmerkungen, die zusätzliche Informationen zu den Daten enthalten, eingeschlossen werden und für diese zugrunde liegenden Attribute, die nicht von einer einzelwertige Navigationseigenschaft vertreten werden, angezeigt werden.Weitere Informationen:Abrufen von Daten zu Sucheigenschaften

Navigationseigenschaften

In OData erlauben Navigationseigenschaften, dass Sie auf Daten zugreifen können, die sich auf die aktuelle Entität beziehen. Wenn Sie eine Entität abrufen, können Sie festlegen, das Navigationseigenschaften zu erweitern, um die zugehörigen Daten einzuschliessen. Es gibt zwei Arten von Navigationseigenschaften: einzelwertige und sammlungswertige.

Einzelwertige Navigationseigenschaften

Diese Einzelwertigen Navigationseigenschaften entsprechen Suchattributen, die viel-zu-ein-Beziehungen unterstützen und eine Referenz auf eine andere Entität einstellen dürfen. Im CSDL EntityType-Element werden diese als NavigationProperty-Element mit einem Type Attributsatz definiert, das als einzelnen Typ festgelegt ist. Nachfolgend finden Sie ein Beispiel der account EntityTypecreatedby einzelwertigen Navigationseigenschaft in CSDL:

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

Jede Navigationseigenschaft, die eine einzewertige Navigationseigenschaft darstellt, hat eine entsprechende sammlungswertige Navigationseigenschaft, die vomPartner Attributswert angegeben ist. Jede einzelwertige Navigationseigenschaft ist auch ein ReferentialConstraint-Element mit Property Attributwert, der die berechnete, schreibgeschützte Sucheneigenschaft darstellt, die verwendet werden kann, um entsprechende GUID-Wert der verknüpften Entität abzurufen.Weitere Informationen:Such-Eigenschaften

Gemeinsam bewertete Navigationseigenschaften

Diese Eigenschaften entsprechen ein-zu-vielen oder viel-zu-vielen Verhältnissen. Im CSDL EntityType-Element werden diese als NavigationProperty-Element mit einem Type Attributsatz definiert, das als einzelnen Typ festgelegt ist. Im Folgenden wird die account EntityTypeAccount_Tasks sammlungswertige Navigationseigenschaft dargestellt, die eine ein-zu-vielen Beziehung darstellt.

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

Wenn die sammlungswertige Navigationseigenschaft eine n: n-Beziehung darstellt, sind der Name der Navigationseigenschaft und der Name des Partners identisch. Im Folgenden wird die account EntityTypeaccountleads_association sammlungswertige Navigationseigenschaft dargestellt, die eine n:n-Beziehung darstellt.

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

Der Unterschied zwischen 1:n- und n:n-Beziehungen ist wichtig, wenn Web API verwendet wird. Die Art, wie Sie Entitäten zuordnen, ist immmer gleich, unabhängig vom Typ der Beziehung. Die n: n-Beziehungen verwenden weiterhin überschneidende Entitäten im Hintergrund, nur einige spezielle Systgementitäten sind imWeb API EntityType Reference enthalten. Beispielsweise ist campaignactivityitem EntityType technisch eine überschneidende Entität, aber ist eingeschlossen, weil sie mehr Eigenschaften hat als eine gewöhnliche überschneidende Entität.

Ein normale überschneidene Entität hat nur die folgenden vier grundlegenden Eigenschaften, um n: n-Beziehung zu verwalten. Wenn Sie eine angepasste n: n-Beziehung zwischen Entitäten erstellen, wird eine normale überschneidende Entität erstellt, um die Beziehung zu unterstützen. Da Sie Navigationseigenschaften verwenden sollen, um Vorgänge auszuführen, die n: n-Beziehungen einbeziehen, sind normale überschneidende Entitäten nicht vollständig dokumentiert können aber weiterhin mithilfe vom Web API zur verfügung stehen. Auf diese überschneidenden Entitätstypen kann über einen festgelegten Entitätsnamen zugegriffen werden, der folgende Namenskonvention verwendet: <intersect entity logical name>" + 'collection'. Beispielsweise können Sie Informationen vom contactleads überschneidenden Entitätstyp mithilfe von [Organisations-URI]/api/data/v8.2/contactleadscollection abrufen. Sie sollten diese normalen überschneidenden Entitäten nur verwenden, wenn Sie Änderungen nachverfolgen möchten.

Aktionen

Aktionen sind Vorgänge, die Nebenwirkungen, wie Datenänderung zulassen und nicht weiter zusammengesetzt werden können, um ein nicht deterministisches Verhalten zu vermeiden.

Das Web API Action Reference Thema enthält jede der verfügbaren Systemmaßnahmen.Weitere Informationen:Nutzen von Web-API-Aktionen.

Funktionen

Funktionen sind Vorgänge, die keine Nebenwirkungen aufweisen und weitere Zusammensetzung unterstützen können, beispielsweise zusätzliche Filtervorgänge, Funktionen oder eine Aktion.

Es gibt zwei Arten von Funktionen im Web API:

• Das Web API Function Reference Thema enthält jede der verfügbaren Systemfunktionen.

• Das Web API Query Function Reference Thema führt Funktionen auf, die als Kriterien in einer Abfrage verwendet werden.

Weitere Informationen:Nutzen von Web-API-Funktionen

Komplexe Typen

Komplexe Typen sind schlüssellose benannte strukturierte Typen, die einen Satz von Eigenschaften enthalten. Komplexe Typen werden als Eigenschaftswerte in Modelentitäten oder als Parameter oder Rückgabewerte für Vorgänge verwendet.

Web API ComplexType Reference enthält alle systemkomplexen Typen.Komplexe Typen sind schlüssellose benannte strukturierte Typen, die einen Satz von Eigenschaften enthalten. Sie werden allgemein als Eigenschaftswerte in Modelentitäten oder als Parameter oder Rückgabewerte für Vorgänge verwendet. Nachfolgend finden Sie die WhoAmIResponse ComplexType der 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>

Enumerationstypen

Enumerationstypen oder EnumTypen weden primitive Typen genannt, deren Werte Konstanten mit zugrunde liegenden ganzzahligen Werten benannt sind.

Web API EnumType Reference enthält alle Enumerationstypen.Enumerationstypen nennt man primitive Typen, deren Werte Konstanten mit zugrunde liegenden ganzzahligen Werten lauten. Nachfolgend finden Sie die AccessRights EnumType der 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>

Siehe auch

Verwenden der Microsoft Dynamics 365-Web-API
Authentifizieren von Microsoft Dynamics 365 mit der Web-API
Vorgänge mithilfe der Web-API ausführen

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright