Grundlegende Vorgänge bei Segmenten mithilfe der Segmentierungs-API

Artikel
03/10/2022
5 Minuten Lesedauer

Ein Marktsegment ist eine Sammlung von Kontakten, auf die Sie eine Marketingkampagne ausrichten. In einigen Fällen sind Kampagnen auf all Ihre Kontakte ausgerichtet, aber in den meisten Fällen wählen Sie anhand demografischer oder firmografischer Daten und anderer Faktoren eine bestimmte Zielgruppe aus. Weitere Informationen: Verwenden von Segmenten.

Die API Segmentierung ermöglicht die programmgesteuerte Interaktion mit Segmentdatensätzen. Die Segmentierungs-API nutzt die Standard-Microsoft Dataverse Web-API zum Bearbeiten von Entitäten oder Nachrichten. Weitere Informationen: Verwenden der Microsoft Dataverse-Web-API. Wenn Sie ein Segment erstellen, werden die Eigenschaften des Segments in der Entität msdyncrm_segment gespeichert. Sie können die Entitätsmetadaten-Informationen mithilfe von @odata.context in der GET-Antwort durchsuchen.

Hinweis

Bevor Sie Vorgänge ausführen, sollten Sie Dynamics 365 Marketing installieren.

In diesem Thema wird gezeigt, wie Sie die Grundvorgänge in der Entität msdyncrm_segment ausführen. Sie müssen die folgenden Pflichtfelder angeben, um ein Segment zu erstellen.

Anzeigename	Schemaname	Value	Erforderlich
Name	msdyncrm_segmentname	Name des Segments.	Ja.
Segmenttyp	msdyncrm_segmenttype	Segmenttyp Es gibt drei Arten von Segmenten: - Statisch `192350001` - Dynamisch: `192350000` - Zusammengesetzt `192350002`	Ja.
Statusgrund	statuscode	Aktueller Status des Segments. Das sind die verfügbaren Statuscodes: - Entwurf `192350000` - Live `192350001` - Beendet `192350002` - GoingLive `192350006` - Wird beendet `192350007`	Ja.
Segmentabfrage	msdyncrm_query	Abfrage in der Segmentierungsabfrage.	Ja (nur für dynamische und zusammengesetzte Segmente).

Um die Vorgänge zu testen, können Sie das Postman-Tool verwenden. Weitere Informationen: Postman mit Web-API verwenden

CRUD-Vorgänge auf statischen Segmenten

Dieser Abschnitt zeigt, wie grundlegende CRUD-Vorgänge (Erstellen, Aktualisieren, Abrufen und Löschen) an statischen Segmenten ausgeführt werden.

Erstellungsanforderung

Diese Anforderung erstellt ein neues statisches Segment mit zwei Kontakten und statuscode festgelegt auf Draft. Die Antwortkopfzeile enthält die URL für diesen neu erstellte Datensatz (Entitätsinstanz),, der in Klammern die eindeutige ID (segmentID) für den Datensatz enthält.

Wichtig

Sie müssen OrgUrl durch https://<add your environment name, like ‘myorg.crm’>.dynamics.com ersetzen. Sie können den Umgebungsnamen auch von Einstellungen -> Anpassungen -> Entwicklerressourcen abrufen.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
  "msdyncrm_segmentname": "StaticSegmentApi1",
  "msdyncrm_segmenttype": 192350001,
  "msdyncrm_segmentmemberids": "[\"crm1405f4ba-1ee9-e811-a99d-000d3a35f12f\",\"crm0604cdd1-1ee9-e811-a99d-000d3a35f12f\"]",
  "statuscode": 192350000
}

Wichtig

Der Zweck des Präfixes crm ist es, den Typ des Datensatzbezeichners eindeutig anzugeben. Dies ist erforderlich, wenn Sie eine veraltete Segmentierungslösung verwenden, die standardmäßig einen anderen Bezeichnertyp verwendet.

Updateanforderung

Mit der Updateanforderung aktualisieren Sie den statuscode des statischen Segments zu Going Live (192350006). Wenn die Anforderung ausgeführt wird, aktualisiert sie statuscode auf Live.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
  "statuscode": 192350006
}

Abrufanforderung

Mit der Abrufanforderung rufen Sie alle statischen Segmente ab, die sich im Live Status befinden.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350001

Sie können auch Segmente mit spezifischen Eigenschaften abrufen.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$select=msdyncrm_segmentid,msdyncrm_segmentname,msdyncrm_segmentquery,msdyncrm_description

Löschungsanforderung

Mit der Löschungsanforderung löschen Sie das erstellte statische Segment.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

CRUD-Vorgänge auf dynamischen Segmenten

Dieser Abschnitt zeigt, wie grundlegende CRUD-Vorgänge (Erstellen, Aktualisieren, Abrufen und Löschen) an dynamischen Segmenten ausgeführt werden. Dynamische Segmente basieren auf der Segmentabfrage (msdyncrm_segmentquery). Weitere Informationen: Segmentabfragedefinition.

Erstellungsanforderung

Diese Anforderung erstellt ein dynamisches Segment und legt statuscode auf Draft fest.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
    "msdyncrm_segmentname": "Customers with name and email",
    "msdyncrm_segmentquery": "PROFILE(contact, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1) && ISNOTNULL(contact_1.fullname))",
    "msdyncrm_segmenttype": 192350000,
    "statuscode": 192350000
}

Die folgende Anforderung erstellt ein dynamisches Segment mit einer bedingten Segmentabfrage, um nur Kontakten abzurufen, bei denen das Feld address1_city auf NewYork oder NewJersey festgelegt ist.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
    "msdyncrm_segmentname": "MySegment2",
    "msdyncrm_segmentquery": "PROFILE(contact).FILTER((address1_city == 'NewYork' || address1_city == 'NewJersey'))",
    "msdyncrm_segmenttype": 192350000,
    "statuscode": 192350006
}

Die folgende Anforderung erstellt ein neues dynamisches Segment und legt statuscode auf Going Live fest.

POST api/data/v9.0/msdyncrm_segments
{

  "msdyncrm_segmentname": "Customers with name and email",
  "msdyncrm_segmenttype": 192350000,
  "msdyncrm_segmentquery": "PROFILE(contact, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1) && ISNOTNULL(contact_1.fullname))",
  "statuscode": 192350006
}

Updateanforderung

Mit der Updateanforderung aktualisieren Sie den Status des dynamischen Segments auf Going Live.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
    "statuscode": 192350006
}

Hinweis

Es wird empfohlen, die Segmente nicht direkt in den Live Zustand zu verschieben.

Abrufanforderung

Mit der Abrufanforderung rufen Sie alle dynamischen Segmente ab, die sich im Stop Status befinden.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350002

Löschungsanforderung

Mit der Löschungsanforderung löschen Sie das dynamische Segment, das erstellt ist.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

CRUD-Vorgänge auf zusammengesetzteb Segmenten

Dieser Abschnitt zeigt, wie grundlegende CRUD-Vorgänge (Erstellen, Aktualisieren, Abrufen und Löschen) an zusammengesetzten Segmenten ausgeführt werden.

Erstellungsanforderung

Diese Anforderung erstellt ein zusammengesetztes Segment und legt statuscode auf Going Live fest.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
    "msdyncrm_segmentname": "my_compound_segment1",
    "msdyncrm_segmenttype": 192350002,
    "msdyncrm_query":"SEGMENT(segment1) UNION SEGMENT(segment2)",
    "statuscode": 192350006
}

Updateanforderung

Mit der Updateanforderung aktualisieren Sie den Status des zusammengesetzten Segments auf Stopping.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
    "statuscode": 192350007
}

Hinweis

Es wird empfohlen, die Segmente nicht direkt in den Stopped Zustand zu verschieben.

Abrufanforderung

Mit der Abrufanforderung rufen Sie alle zusammengesetzten Segmente ab, die sich im Stop Status befinden.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350002

Löschungsanforderung

Mit der Löschungsanforderung löschen Sie das zusammengesetzte Segment, das erstellt ist.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

Kontakt aus einem statischen Segment entfernen/hinzufügen

Segmentmitglieder können zu Segmenten hinzugefügt bzw. von statischen Kontaktsegmenten entfernt werden. Sie können Kontakte hinzufügen/entfernen, indem Sie entweder eine Abfragedefinition oder bestimmte Kontakt-IDs angeben.

Einige der wichtigen Aspekte, die berücksichtigt werden müssen, wenn Hinzufügen/Entfernen-Vorgänge an Segmentmitgliedern ausgeführt werden:

Nur Instanzen des Entitätstyps Kontakt können als Mitglieder hinzugefügt/entfernt werden.
Wenn die angegebenen Kontakt-IDs nicht vorhanden sind, werden sie ignoriert.
Mitgliederanforderungen hinzufügen/entfernen werden asynchron verarbeitet.
Sie können Kontakte hinzufügen/entfernen, indem Sie Endpunkt mehrmals aufrufen, normalerweise in Stapeln von jeweils bis zu 20.000 Kontakten.

Fügen Sie Segmentmitglieder hinzu, indem Sie IDs angeben

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
   "msdyncrm_segmentid": "59AC8BBF-57E7-E811-A9A9-000D3A35F403",
   "msdyncrm_operation": "addByIds",
   "msdyncrm_memberids": "[\"B5672BDB-8899-43CB-9FA1-0AE4DC61DAD3\", \"694E1C8E-F704-4B23-9B07-E65DB1620E47\", \"A4A31E3D-DFCA-4765-8018-3BA7D5E376C7\"]"
}

Entfernen Sie Segmentmitglieder, indem Sie IDs angeben

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
   "msdyncrm_segmentid": "59AC8BBF-57E7-E811-A9A9-000D3A35F403",
   "msdyncrm_operation": "removeByIds",
   "msdyncrm_memberids": "[\"B5672BDB-8899-43CB-9FA1-0AE4DC61DAD3\", \"694E1C8E-F704-4B23-9B07-E65DB1620E47\", \"A4A31E3D-DFCA-4765-8018-3BA7D5E376C7\"]"
}

Fügen Sie Segmentmitglieder hinzu, indem Sie Abfragen angeben

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
    "msdyncrm_segmentid": "b5466fbb-2cef-e911-a81d-000d3a6d200c",
    "msdyncrm_operation": "addByQuery",
    "msdyncrm_query": "PROFILE(account, account_1).FILTER(account_1.accountid == '1cc00a15-37ef-e911-a81d-000d3a6d200c').TRAVERSE(contact_account_parentcustomerid, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1))"
}

Entfernen Sie Segmentmitglieder hinzu, indem Sie Abfragen angeben

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
    "msdyncrm_segmentid": "b5466fbb-2cef-e911-a81d-000d3a6d200c",
    "msdyncrm_operation": "removeByQuery",
    "msdyncrm_query": "PROFILE(account, account_1).FILTER(account_1.accountid == '1cc00a15-37ef-e911-a81d-000d3a6d200c').TRAVERSE(contact_account_parentcustomerid, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1))"
}

Status ausstehender Vorgänge abrufen

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
    "msdyncrm_segmentid":"b5466fbb-2cef-e911-a81d-000d3a6d200c",
    "msdyncrm_operation":"getState"
}

Segmentmitglieder abrufen (empfohlen)

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_FetchContactsByQuery
{
    "Query":"(SEGMENT(SEGMENT_CRM_ID_e1fa7fdc5c78ea11a811000d3a8e8fcc)).ORDERBY(fullname ASC).SKIP(0).TAKE(15).SELECT(contactid)",
    "FetchXml":"<fetch version=\"1.0\" output-format=\"xml-platform\" mapping=\"logical\" count=\"15\" page=\"1\" returntotalrecordcount=\"true\"><entity name=\"contact\"><attribute name=\"fullname\"/><attribute name=\"emailaddress1\"/><attribute name=\"company\"/><attribute name=\"parentcustomerid\"/><attribute name=\"contactid\"/><order attribute=\"fullname\" descending=\"false\"/></entity></fetch>","OwningBusinessUnit":"0b4b85cc-7f6c-ea11-a811-000d3a54d359",
    "Scope":270100000,
    "TimeZone":null
}

Wichtig

Ersetzen Sie im obigen Beispiel SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc durch den Namen Ihres Segments im Backend, wie es im Feld msdyncrm_segmentqueryname Ihres Segments steht. Wenn Ihr Segment eine ID hat ce97cb9d-bd75-ea11-a811-000d3a8e8fcc, wird dieser Wert SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc sein.

Abrufen von Segmentmitglieder (veraltet)

GET {{OrgUrl}}/api/data/v9.0/contacts?fetchXml=fetch version="1.0" output-format="xml-platform" mapping="logical" returntotalrecordcount="true" page="1" count="5" no-lock="false">
    <entity name="contact">
        <attribute name="fullname"/>
        <attribute name="contactid"/>
        <order attribute="fullname" descending="false"/>
        <link-entity name="msdyncrm_segment" from="msdyncrm_segmentid" to="msdyncrm_segmentmemberid" alias="bb">
            <filter type="and">
                <condition attribute="msdyncrm_segmentid" operator="eq" uitype="msdyncrm_segment" value="bfc9d5d6-d6aa-e911-a859-000d3a3159df"/>
            </filter>
        </link-entity>
    </entity>
</fetch>

Segmente werden validiert

Vor dem Erstellen oder dem Ändern eines Segments können Sie die neue Umfragefunktion Definition mithilfe eines dedizierten Überprüfungsendpunkts überprüfen. Der Endpunkt gibt immer eine HTTP-Status-OK-Nachricht und ein Objekt mit der Eigenschaft ValidationResult mit einem Array von Fehlern zurück.

Im Falle einer gültigen Definition wird das Ergebnisarray leer angezeigt. Andernfalls enthält es Datensätze für die identifizierten Probleme. Die Segmentdefinition wird bei der Erstellung des Datensatzes überprüft, und der Statuscode wird auf Live gehen gesetzt.

Die Validierung wird absichtlich übersprungen, wenn ein Segment im Zustand Draft angelegt wird. Auch eine fehlgeschlagene Validierung führt zu HTTP 400 mit einer Fehlermeldung im Antworttext.

Überprüfen einer gültigen Segmentdefinition

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ValidateSegment
{
       "msdyncrm_segmentname":"NewSegment",
       "msdyncrm_segmentquery":"PROFILE(contact)",
       "msdyncrm_segmenttype":192350000,
       "statuscode":192350000
}

Antwort

{
…
    "ValidationResult": "[]"
}

Eine ungültige Segmentdefinition überprüfen

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ValidateSegment
{
       "msdyncrm_segmentname":"NewSegment",
       "msdyncrm_segmentquery":"PROFILE(UnknownEntity)",
       "msdyncrm_segmenttype":192350000,
       "statuscode":192350006
}

Antwort

{
…
    "ValidationResult": "[{\"ErrorCode\":\"SegmentDciValidator_SegmentInvalid\",\"FieldName\":\"msdyncrm_query\"}]"
}

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

Grundlegende Vorgänge bei Segmenten mithilfe der Segmentierungs-API

CRUD-Vorgänge auf statischen Segmenten

CRUD-Vorgänge auf dynamischen Segmenten

CRUD-Vorgänge auf zusammengesetzteb Segmenten

Kontakt aus einem statischen Segment entfernen/hinzufügen

Segmente werden validiert

Feedback