Erstellen einer Tabellenzeile über die Web-API

Senden Sie eine POST Anforderung an die Web-API-Entityset-Ressource, um eine Tabellenzeile (Entitätsdatensatz) in Microsoft Dataverse zu erstellen. Sie können mehrere verknüpfte Tabellenzeilen in einem einzigen Vorgang erstellen, indem Sie deep insert verwenden. Sie müssen auch wissen, wie Werte festgelegt werden, um eine neue Tabellenzeile mit vorhandenen Tabellen zu verknüpfen, indem Sie die @odata.bind Anmerkung verwenden.

Grundlegende Erstellung

In diesem Beispiel wird ein neuer Datensatz für die Entität "Konto" 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)

Zum Erstellen eines Datensatzes müssen Sie den gültigen Entitätssatznamen, Eigenschaftennamen 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 verfügt über eine eindeutige Bezeichner-Primärschlüsselspalte, die Sie beim Erstellen einer Zeile angeben können. In den meisten Fällen sollten Sie dem System erlauben, diesen Wert für Sie festzulegen, da die vom System generierten Werte für eine optimale Leistung optimiert sind.

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.

Mithilfe von elastischen Tabellen können Sie Datensätze mit doppelten Primärschlüsselwerten und unterschiedlichen partitionid Werten erstellen. Dieses Muster ist jedoch nicht mit modellgesteuerten Power Apps oder Canvas-Apps kompatibel. Erfahren Sie, wie Sie den Primärschlüsselwert mit elastischen Tabellen festlegen.

Erstellen mit den zurückgegebenen Daten

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

Um zu steuern, welche Eigenschaften zurückgegeben werden, fügen Sie die $select Abfrageoption an die URL für den Entitätssatz an. Sie können auch $expand verwenden, um verwandte Entitäten zurückzugeben.

Geschachtelte $expand-Navigationseigenschaften mit Sammlungswerten geben keine Daten zurück, wenn sie mit der return=representation-Präferenz verwendet werden. Weitere Informationen finden Sie unter "Geschachtelte $expand für Eigenschaften der Sammlungswertnavigation".

Wenn Sie eine Entität mithilfe dieser Methode erstellen, wird der OData-EntityId Header, der den URI für den erstellten Datensatz enthält, nicht zurückgegeben.

Im folgenden Beispiel wird eine neue Kontoentität erstellt und die angeforderten Daten in der Antwort zurückgegeben.

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

Verwenden Sie die CreateMultiple-Aktion, um schnell mehrere Datensätze desselben Typs in einer einzigen Anforderung zu erstellen. Zum Zeitpunkt dieses Schreibens wird createMultiple-Aktion nicht von allen Standardtabellen unterstützt, aber alle elastischen Tabellen unterstützen sie.

Weitere Informationen findest du unter:

• Nachrichten zu Massenoperationen
• Beispiel: SDK für .NET Massenoperationen nutzen
• CreateMultiple mit elastischen Tabellen verwenden

Erstellen Sie zusammenhängende Tabellenzeilen in einem Arbeitsgang

Mithilfe von Standardtabellen können Sie Entitäten erstellen, die miteinander in Beziehung stehen, indem Sie sie als Navigationseigenschaftswerte definieren. Dieses Muster ist bekannt als tiefes Einfügen. Diese Methode hat zwei Vorteile. Es ist effizienter, da es mehrere einfachere Erstellungs- und Zuordnungsvorgänge durch einen kombinierten Atomvorgang ersetzt. Ein atomarer 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 URIs der erstellten verknüpften Entitäten werden nicht zurückgegeben. Sie können die Primärschlüsselwerte der Datensätze mithilfe der Prefer: return=representation Kopfzeile abrufen, sodass sie die Werte des erstellten Datensatzes zurückgibt. Erfahren Sie mehr über das 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 firstname und lastname Werten erstellt, da Sie ihn als Objekteigenschaft der einwertigen Navigationseigenschaft mit dem Namen primarycontactiddefinieren.

• Eine Gelegenheit in Verbindung mit dem Konto wird erstellt, da Sie es als Objekt in einem Array definieren, das auf den Wert einer sammlungswertigen Navigationseigenschaft mit dem Namen opportunity_customer_accounts festgelegt ist.

• Eine Aufgabe im Zusammenhang mit der Möglichkeit wird erstellt, da Sie diese als Objekt in einem Array definieren, das auf den Wert einer kollektionsbasierten Navigationseigenschaft mit dem Namen 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

Wenn Sie beim Erstellen neue Datensätze mit vorhandenen Datensätzen verknüpfen möchten, verwenden Sie die @odata.bind Anmerkung, 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 Anforderung verwendet den Prefer: return=representation Header, sodass er die Werte des erstellten Datensatzes zurückgibt. Weitere Informationen finden Sie unter Erstellen mit zurückgegebenen Daten.

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 unterdrückt das System die duplizierte Erkennung, wenn Sie Datensätze erstellen. Um die Duplikaterkennung zu aktivieren, schließen Sie den MSCRM.SuppressDuplicateDetection: false Header mit Ihrer POST Anforderung 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 findest du unter:

• Erkennen von doppelten Daten mit Code
• Erkennen von doppelten Daten mit der Web-API
• Erkennen von doppelten Daten mit dem SDK für .NET

Erstellen eines Datensatzes aus einem anderen Datensatz

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

• Spalten der Tabelle zuordnen
• Anpassen von Tabellen- und Spalten-Zuordnungen

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 POST den Daten zum Erstellen des Datensatzes.

Das folgende Beispiel zeigt, wie Sie einen Kontodatensatz mithilfe der Werte eines vorhandenen Kontodatensatzes mit einem accountid Wert erstellen, der 00000000-0000-0000-0000-000000000001gleich ist.

Schritt 1: Abrufen der Daten mithilfe von 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 Sie von InitializeFrom erhalten, enthält die zugeordneten Werte der Spalten zwischen der Quelltabelle und der Zieltabelle sowie die GUID des übergeordneten Datensatzes. Die Spaltenzuordnung zwischen Tabellen, die miteinander in Beziehung stehen, variiert je nach Tabelle und Organisation, wodurch die Antwort von InitializeFrom unterschiedlich ausfällt.

Sie können andere Eigenschaftswerte für den neuen Datensatz festlegen oder ändern, indem Sie sie im JSON-Anforderungstext hinzufügen, wie im folgenden Beispiel gezeigt:

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, erstellen Sie die Entitäten in Speicherpartitionen, um den Zugriff auf diese Entitätseinträge 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 Fehler 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
Einen anderen Benutzer mit der Web-API übernehmen
Bedingte Vorgänge mithilfe der Web-API ausführen