Erstellen einer Entität mithilfe des Web-API

Artikel
10/31/2017

Veröffentlicht: Januar 2017

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

Nutzen Sie eine POST-Anfrage, um eine Daten zum Erstellen einer Entität zu senden. Sie können mehrere verknüpfte Entitäten in einem einzelnen Vorgang erstellten, indem Sie die "tiefe Einfügung" nutzen. Sie müssen auch damit vertraut sein, wie Sie Werte festlegen, um eine neue Entität mit vorhandenen Entitäten mithilfe der @odata.bind-Anmerkung zuzuordnen.

Hinweis

Informationen dazu, wie der Entitätsmetadaten mithilfe der Web-API erstellt und aktualisiert werden können, finden Sie unter Erstellen und Aktualisieren von Entitätsdefinitionen mit der Web-API.

In diesem Thema

Grundlegende Erstellung

Erstellen verknüpfter Entitäten in einem Vorgang

Entitäten bei Erstellung zuordnen

Erstellen mit den zurückgegebenen Daten

Grundlegende Erstellung

In diesem Beispiel wird eine neue Firmenentität erstellt. Der OData-EntityId-Antwortheader enthält die URI der erstellten Entität.

Anforderung

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Antwort

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

Zum Erstellen einer neuen Entität müssen Sie die passenden Eigenschaftennamen und -arten ermitteln. Für alle Systementitäten und Attribute können Sie diese Informationen im Thema für diese Entität unter Web API EntityType Reference finden. Informationen zu benutzerdefinierten Entitäten oder Attributen finden Sie in der Definition der Entität im d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdlWeitere Informationen:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_entityTypes

Erstellen verknüpfter Entitäten in einem Vorgang

Sie können die Entitäten, die miteinander verknüpft werden, indem Sie sie als Navigationseigenschaftenwerte definieren. Dies ist bekannt als tiefe Einfügung.

Wie bei einem grundlegenden Erstellen enthält die Antwort-OData-EntityId-Kopfzeile die Uri der erstellten Entität. Die für die erstellten URI verknüpften Entitäten werden nicht zurückgegeben.

Beispielsweise erstellt der folgenden Anforderungstext, der mit der Account-Entität veröffentlicht wurde, insgesamt vier neue Entitäten beim Erstellen eines Kontos.

Ein Kontakt wird erstellt, da er als eine Objekteigenschaft der einwertigen Navigationseigenschaft primarycontactid definiert ist.
Eine Verkaufschance wird erstellt, da sie als Objekt in einem Arrays definiert ist, das auf den Wert einer als Sammlung bewerteten Navigationseigenschaft opportunity_customer_accounts festgelegt ist.
Eine Aufgabe wird erstellt, da sie als Objekt in einem Arrays definiert ist, das auf den Wert einer als Sammlung bewerteten Navigationseigenschaft Opportunity_Tasks festgelegt ist.

Anforderung

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "John",
     "lastname": "Smith"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

Antwort

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Entitäten bei Erstellung zuordnen

Um neue Entitäten vorhandene Entitäten zuzuordnen wenn diese erstellt werden, müssen Sie den Wert für Einzelwert-Navigationseigenschaften über die @odata.bind-Notation festlegen.

Der folgende Anforderungstext, der im Firmenentitätssatz veröffentlicht wird, erstellt eine neue Firma, der ein vorhandener Kontakt mit dem contactid-Wert von 00000000-0000-0000-0000-000000000001 zugeordnet ist.

Anforderung

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
"name":"Sample Account",
"primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"
}

Antwort

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000002)

Hinweis

Das Zuordnen von Entitäten auf diese Weise mithilfe einer Eigenschaft "als Sammlung bewertet" wird von der Internet-API nicht unterstützt.

Erstellen mit den zurückgegebenen Daten

Hinweis

Diese Funktion wurde mit Update für Dynamics 365 (online und lokal), Dezember 2016 hinzugefügt.

Sie können Ihre POST-Anforderung so zusammen stellen, dass die Daten aus dem erstellten Datensatz mit dem Status 201 (Created) zurückgegeben werden. Um dieses Ergebnis zu erzielen, müssen Sie die return=representation-Einstellung in den Anforderungsheadern verwenden.

Um die zurückgegebenen Eigenschaften zu steuern, hängen Sie die $select-Abfrageoption für die URL im Entitätssatz an. Wenn sie verwendet wird, wird die $expand -Abfrageoption ignoriert.

Wenn eine Entität auf diese Weise erstellt wird, wird der OData-EntityId-Header mit der URI für den erstellten Datensatz nicht zurückgegeben.

In diesem Beispiel wird eine Firmaenentität erstellt und gibt die angeforderten Daten in der Antwort zurück.

Anforderung

POST cc_WebAPI_ServiceURI/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Antwort

HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts/$entity",
    "@odata.etag": "W/\"536530\"",
    "accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Sample Account",
    "createdon": "2016-09-28T22:57:53Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Siehe auch

Beispiel grundlegender Web-API-Operationen (C#)
Beispiele grundlegender Web API-Operationen (clientseitiges JavaScript)
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen verfassen und Fehler beheben
Datenabfrage mit Web-API
Abrufen einer Entität mithilfe des Web-API
Entitäten aktualisieren und löschen mithilfe der Web API
Entitäten zuordnen und Zuordnungen aufheben mithilfe der Web API
Nutzen von Web-API-Funktionen
Nutzen von Web-API-Aktionen
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen

Microsoft Dynamics 365

Freigeben über

Erstellen einer Entität mithilfe des Web-API

In diesem Thema

Grundlegende Erstellung

Erstellen verknüpfter Entitäten in einem Vorgang

Entitäten bei Erstellung zuordnen

Erstellen mit den zurückgegebenen Daten

Siehe auch

Zusätzliche Ressourcen