Erstellen einer Tabellenzeile über die Web-API

  • Artikel

Verwenden Sie eine POST-Abfrage, um Daten zu senden, um eine Tabellenzeile (Datensatz einer Entität) zu erstellen. Sie können mehrere zusammenhängende Tabellenzeilen in einer einzigen Operation erstellen, indem Sie Tiefes Einfügen verwenden. Sie müssen auch wissen, wie Sie Werte setzen, um eine neue Tabellenzeile mit bestehenden Tabellen zu verknüpfen, indem Sie die @odata.bind-Anmerkung verwenden.

Hinweis

Informationen über das Erstellen und Aktualisieren von Tabellendefinitionen (Entitäten) mithilfe der Web-API finden Sie unter Erstellen und Aktualisieren von Tabellendefinitionen mithilfe der Web-API.

Grundlegende Erstellung

In diesem Beispiel wird ein neuer Datensatz für eine Entität eines Kontos erstellt. accounts ist der Entitätssatzname für den account EntityType. Der Antwort-OData-EntityId-Header enthält die URI der erstellten Entität.

Anforderung:


POST [Organization URI]/api/data/v9.2/accounts
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: [Organization URI]/api/data/v9.2/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

Um einen Datensatz zu erstellen, müssen Sie die gültigen Name der Entität, Eigenschaftsnamen und Typen identifizieren. Für alle Systemtabellen und Attribute (Tabellenspalten) finden Sie diese Informationen im Artikel für diese Entität in der Web-API-Entitätstypreferenz. Informationen zu benutzerdefinierten Tabellen oder Spalten finden Sie in der Definition der Tabelle im CSDL $metadata document. Weitere Informationen: Web API-EntityTypes

Den Primärschlüsselwert festlegen

Jede Tabelle hat eine eindeutige Primärschlüsselspalte, die Sie beim Erstellen einer Zeile angeben können. In den meisten Fällen empfiehlt das System, dass Sie diese Option festlegen, da die Werte, die vom System generiert werden, für eine bestmögliche Leistung optimiert werden.

Mit elastischen Tabellen können Sie Datensätze mit doppelten Primärschlüsselwerten und unterschiedlichen partitionid-Werte erstellen. Dieses Muster ist jedoch nicht mit modellgesteuerten oder Canvas-Power Apps kompatibel. Erfahren Sie mehr über das Festlegen des Primärschlüsselwerts mit elastischen Tabellen

Erstellen mit den zurückgegebenen Daten

Sie können Ihre POST-Anforderung so zusammenstellen, 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. Sie können auch $expand verwenden, um verknüpfte Entitäten zurückzugeben.

Verschachteltes $expand auf sammlungswertigen Navigationseigenschaften wird bei Verwendung mit der return=representation-Einstellung keine Daten zurückgegeben. Weitere Informationen: Verschachteltes $expand für sammlungswertige Navigationseigenschaften

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 [Organization URI]/api/data/v9.2/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon
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
}

Antwort:


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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$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"
}

Erstellen Sie mehrere Datensätze in einer einzigen Anfrage

Der schnellste Weg, mehrere Datensätze desselben Typs in einer einzigen Anfrage zu erstellen, ist die Verwendung der CreateMultiple-Aktion. Zum Zeitpunkt des Verfassens dieses Artikels die CreateMultiple-Aktion. Nicht alle Standardtabellen unterstützen diese Aktion, alle elastischen Tabellen jedoch.

Weitere Informationen:

Bei Standardtabellen können Sie Entitäten, die miteinander verknüpft werden, indem Sie sie als Navigationseigenschaftenwerte definieren. Dieses Muster ist bekannt als tiefes Einfügen. Diese Methode hat zwei Vorteile. Es ist effizienter, denn es ersetzt mehrere einfachere Erstellungs- und Zuordnungsvorgänge durch einen kombinierten atomaren Vorgang. Ein unteilbarer Vorgang ist vollständig erfolgreich oder schlägt vollständig fehl.

Wie bei einem einfachen Erstellen enthält der OData-EntityId Antwort-Header die URI der erstellten Entität. Die für die erstellten URIs verknüpften Entitäten werden nicht zurückgegeben. Sie können die Primärschlüsselwerte der Datensätze abrufen, wenn Sie den Prefer: return=representation-Header verwenden, damit die Werte des erstellten Datensatzes zurückgegeben werden. Weitere Informationen: Mithilfe zurückgegebener Daten erstellen

Der folgende Abfragetext, der an die accounts Entität gesendet wird, erstellt z.B. insgesamt vier Datensätze im Zusammenhang mit dem Erstellen eines Kontos.

  • Ein Kontakt wird erstellt, weil er als eine Objekteigenschaft der einwertigen Navigationseigenschaft primarycontactid definiert ist.

  • Eine Verkaufschance wird erstellt, weil sie als Objekt in einem Array definiert ist, das auf den Wert einer Navigationseigenschaft mit dem Wert opportunity_customer_accounts gesetzt ist.

  • Eine Aufgabe wird erstellt, weil sie ein Objekt in einem Array definiert, das auf den Wert einer sammlungswert Navigationseigenschaft Opportunity_Tasks gesetzt ist.

Hinweis

Wenn Sie eine neue Tabellenzeile erstellen, können Sie nicht gleichzeitig ein nicht primäres Bild einfügen. Damit ein nicht primäres Image hinzugefügt werden kann, muss die Zeile bereits vorhanden sein.

Anforderung:

POST [Organization URI]/api/data/v9.2/accounts
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: [Organization URI]/api/data/v9.2/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Tabellenzeilen bei der Erstellung zuordnen

Um neue Datensätze mit bestehenden Datensätzen zu verknüpfen, wenn sie erstellt werden, verwenden Sie die Anmerkung @odata.bind, um den Wert der Navigationseigenschaften festzulegen.

Der folgende Abfragetext, der an die Entität accounts gesendet wird, erstellt ein Konto, das mit einem bestehenden Kontakt mit dem Wert contactid von 00000000-0000-0000-0000-000000000001 und zwei bestehenden Aufgaben mit den Werten activityid von 00000000-0000-0000-0000-000000000002 und 00000000-0000-0000-0000-000000000003 verbunden ist.

Diese Anfrage verwendet den Prefer: return=representation-Header, damit die Werte des erstellten Datensatzes zurückgegeben werden. Weitere Informationen: Mithilfe zurückgegebener Daten erstellen

Anforderung:


POST [Organization URI]/api/data/v9.2/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Prefer: return=representation

{
    "name": "Sample Account",
    "primarycontactid@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
    "Account_Tasks@odata.bind": [
        "/tasks(00000000-0000-0000-0000-000000000002)",
        "/tasks(00000000-0000-0000-0000-000000000003)"
    ]
}

Antwort:


HTTP/1.1 201 Created
OData-Version: 4.0
Preference-Applied: return=representation

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))/$entity",
    "@odata.etag": "W/\"36236432\"",
    "name": "Sample Account",
    "accountid": "00000000-0000-0000-0000-000000000004",
    "primarycontactid": {
        "@odata.etag": "W/\"28877094\"",
        "fullname": "Yvonne McKay (sample)",
        "contactid": "00000000-0000-0000-0000-000000000001"
    },
    "Account_Tasks": [
        {
            "@odata.etag": "W/\"36236437\"",
            "subject": "Task 1",
            "activityid": "00000000-0000-0000-0000-000000000002"
        },
        {
            "@odata.etag": "W/\"36236440\"",
            "subject": "Task 2",
            "activityid": "00000000-0000-0000-0000-000000000003"
        }
    ]
}

Nach doppelten Datensätzen suchen

Standardmäßig wird die Duplikaterkennung unterdrückt, wenn Sie Datensätze mithilfe der Web-API erstellen. Um die Erkennung von Duplikaten zu aktivieren, fügen Sie den Header MSCRM.SuppressDuplicateDetection: false in Ihre POST-Anfrage ein. Duplikaterkennung gilt nur, wenn die folgenden Bedingungen zutreffen:

  • Die Organisation hat die Erkennung von Duplikaten aktiviert.
  • Die Entität ist für die Erkennung von Duplikaten aktiviert.
  • Aktive Regeln zur Erkennung von Duplikaten werden angewendet.

Weitere Informationen:

Erstellen eines Datensatzes aus einem anderen Datensatz

Verwenden Sie die Funktion InitializeFrom, um einen Datensatz im Kontext eines bestehenden Datensatzes zu erstellen, in dem die Beziehung zwischen den Tabellen zugeordnet ist. Informationen zum Erstellen dieser Zuordnungen finden Sie unter:

Um zu bestimmen, ob zwei Entitäten zugeordnet werden können, können Sie die folgende Abfrage verwenden:

GET [Organization URI]/api/data/v9.2/entitymaps?$select=sourceentityname,targetentityname&$orderby=sourceentityname

Das Erstellen eines neuen Datensatzes aus einem anderen Datensatz ist ein zweistufiger Prozess. Verwenden Sie zunächst die InitializeFrom Funktion, um Eigenschaftswerte zurückzugeben, die dem ursprünglichen Datensatz zugeordnet sind. Dann kombinieren Sie die Antwortdaten, die in der Funktion InitializeFrom zurückgegeben werden, mit allen Änderungen, die Sie vornehmen möchten, und erstellen dann mit POST den Datensatz.

Das folgende Beispiel zeigt, wie Sie einen Kontodatensatz mit den Werten eines vorhandenen Kontodatensatzes mit einem accountid-Wert erstellen, der 00000000-0000-0000-0000-000000000001 entspricht.

Schritt 1: Abrufen der Daten mit InitializeFrom

Anforderung:

GET [Organization URI]/api/data/v9.2/InitializeFrom(EntityMoniker=@p1,TargetEntityName=@p2,TargetFieldType=@p3)?@p1={'@odata.id':'accounts(00000000-0000-0000-0000-000000000001)'}&@p2='account'&@p3=Microsoft.Dynamics.CRM.TargetFieldType'ValidForCreate'
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json

Antwort:

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",
    "@odata.type": "#Microsoft.Dynamics.CRM.account",
    "parentaccountid@odata.bind": "accounts(00000000-0000-0000-0000-000000000001)",
    "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
    "address1_line1": "123 Maple St.",
    "address1_city": "Seattle",
    "address1_country": "United States of America"
}

Schritt 2: Den neuen Datensatz erstellen

Die Antwort, die von der InitializeFrom-Funktion empfangen wird, besteht aus zugeordneten Spalten zwischen Quelltabelle und Zieltabelle und der GUID des übergeordneten Datensatzes. Die Spaltenzuordnung zwischen Tabellen, die eine Beziehung haben, ist für verschiedene Tabellen verschieden und kann angepasst werden, weshalb die Antwort der Anforderung der InitializeFrom-Funktion für verschiedene Organisationen variieren kann.

Andere Eigenschaftswerte können auch für den neuen Datensatz festgelegt und/oder geändert werden, indem sie, wie im folgenden Beispiel gezeigt, zum JSON-Anforderungstext hinzugefügt werden:

POST [Organization URI]/api/data/v9.2/accounts
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    {
        "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",
        "@odata.type": "#Microsoft.Dynamics.CRM.account",
        "parentaccountid@odata.bind": "accounts(00000000-0000-0000-0000-000000000001)",
        "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
        "name":"Contoso Ltd",
        "numberofemployees":"200",
        "address1_line1":"100 Maple St.",
        "address1_city":"Seattle",
        "address1_country":"United States of America",
        "fax":"73737"
    }
}

Erstellen Sie Dokumente in Speicherpartitionen

Wenn Sie eine große Anzahl von Datensätzen für elastische Tabellen erstellen, können Sie die Entitäten in Speicherpartitionen erstellen, um den Zugriff auf diese Entitätsdatensätze zu beschleunigen.

Weitere Informationen: Erstellen eines Datensatzes in einer elastischen Tabelle

Siehe auch

Beispiel für Web-API Grundvorgänge (C#)
Beispiel für grundlegende Web-API-Vorgänge (Client-seitiges JavaScript)
InitializeFrom Funktion
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen erstellen und Fehler behandeln
Abfragen von Daten mithilfe der Web-API
Abrufen einer Tabellenzeile über die Web-API
Aktualisieren und Löschen von Tabellenzeilen über die Web-API
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen über die 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

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).