Freigeben über

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.

Anmerkung

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(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Um einen Datensatz zu erstellen, müssen Sie die gültigen Name der Entität, Eigenschaftsnamen und Typen identifizieren.

Anmerkung

Power AppsWählen Sie beim Anzeigen einer Liste von Tabellen die Option Erweiterte Tools aus>. Wählen Sie Setname kopieren aus , um den Entitätensatznamen für die Tabelle zu kopieren.

Sie können auch API-Link zu den Tabellendaten auswählen, um die obersten 10 Datenzeilen in Ihrem Browser anzuzeigen. Dies funktioniert am besten, wenn Sie eine Browsererweiterung wie JSON Formatter installiert haben, die die zurückgegebenen JSON-Textdaten formatiert.

Der Name der Entitätenmenge ist nicht immer identisch mit dem Sammlungsnamen oder dem Pluralnamen der Tabelle. Er wird in einer separaten Eigenschaft namens EntitySetName gespeichert.

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. Weitere Informationen zu primären Bildern

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.

Dataverse speichert Primärschlüsseldaten in Telemetrie, um die Wartung des Diensts zu unterstützen. Wenn Sie benutzerdefinierte Primärschlüsselwerte angeben, verwenden Sie in diesen Werten keine vertraulichen Informationen.

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 auf sammlungswertigen 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 zum Erstellen von Datensätzen mit zurückgegebenen Daten

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 mit den Werten firstname und lastname erstellt, da er als eine Objekteigenschaft der einwertigen Navigationseigenschaft namens primarycontactid definiert ist.

  • Eine Verkaufschance mit Bezug zum Konto wird erstellt, weil sie als Objekt in einem Array definiert ist, das auf den Wert einer sammlungsbewerteten Navigationseigenschaft namens opportunity_customer_accounts festgelegt ist.

  • Eine Aufgabe im Zusammenhang mit der Verkaufschance wird erstellt, da sie als Objekt in einem Arrays definiert ist, das auf den Wert einer sammlungsbewerteten Navigationseigenschaft namens Opportunity_Tasks festgelegt ist.

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(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

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 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, die dem ursprünglichen Datensatz zugeordnet wurden, zurückzugeben. Kombinieren Sie dann die in der InitializeFrom-Funktion zurückgegebenen Antwortdaten mit allen Änderungen, die Sie vornehmen möchten, und führen dann ein POST der Daten aus, um den Datensatz zu erstellen.

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.

Erfahren Sie mehr über das Erstellen von Datensätzen in einer elastischen Tabelle

Siehe auch

Beispiel grundlegender Web-API-Operationen (C#)
Beispiel für grundlegende Web-API-Vorgänge (clientseitiges JavaScript)
InitializeFrom-Funktion
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen erstellen und Fehlern behandeln
Datenabfrage mit 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
Web-API-Aktionen verwenden
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen