Freigeben über

Customer Insights - Journeys-Segment mittels Web-API erstellen

Sie können mit der Web-API ein Customer Insights - Journeys-Segment erstellen und dabei den gleichen Ansatz verfolgen wie Sie eine beliebige Entität in einer Power App erstellen würden. Beim Erstellen eines Customer Insights - Journeys-Segments müssen Sie zwei Entitäten erstellen: msdynmkt_segmentdefinitions und msdynmkt_segments. Im folgenden Artikel wird gezeigt, wie diese Entitäten erstellt werden.

Segmentdefinitionseinheit erstellen

Die Segmentdefinition stellt ein Marketingsegment oder eine Liste von Zielkunden dar. Um eine Segmentdefinitionseinheit zu erstellen, müssen Sie eine POST-Anforderung an den API-Endpunkt senden:

POST <Organization URL>/api/data/v9.0/msdynmkt_segmentdefinitions

Der Teil <Organisations-URL> sollte durch die tatsächliche URL des API-Endpunkts der Organisation ersetzt werden und <SegmentDefinitionID> sollte durch den eindeutigen Bezeichner der Segmentdefinition ersetzt werden, die Sie aktualisieren möchten.

Nutzdaten

{
    msdynmkt_segmentquery: string,
    statecode: StateCode,
    statuscode: SegmentDefinitionStatusCode,
    msdynmkt_includedmembers: string,
    msdynmkt_excludedmembers: string,
    msdynmkt_disablesegmentrefresh: boolean,
    msdynmkt_segmentrefreshintervalminutes: number
    msdynmkt_sourcesegmentcreatedon: date
    msdynmkt_sourcesegmentcreatedby: string
}

Beschreibung

Die Nutzdaten haben die folgenden Eigenschaften:

  • msdynmkt_segmentquery: Eine Zeichenfolge, die die Abfrage definiert, die zum Definieren des Segments verwendet wird.
  • statecode: Ein Integer-Wert, der den Status der Segmentdefinition angibt. Der Wert kann einer der folgenden sein:
    • 0 = Aktiv
    • 1 = Inaktiv
  • statuscode: Ein Integer-Wert, der den Status der Segmentdefinition angibt. Der Wert kann einer der folgenden sein:
    • 723270000 = Live
    • 723270001 = Entwurf
    • 723270002 = Liveschalten
    • 723270003 = Gelöscht
  • msdynmkt_includedmembers: Eine Zeichenfolge, die eine Liste von GUIDs von Mitgliedern enthält, die in das Segment aufgenommen werden sollen.
  • msdynmkt_excludedmembers: Eine Zeichenfolge, die eine Liste von GUIDs von Mitgliedern enthält, die aus dem Segment ausgeschlossen werden sollen.
  • msdynmkt_disablesegmentrefresh: Ein boolescher Wert, der angibt, ob die automatische Segmentaktualisierung deaktiviert werden soll.
  • msdynmkt_segmentrefreshintervalminutes: Ein Integer-Wert, der das Aktualisierungsintervall in Minuten angibt.
  • msdynmkt_sourcesegmentcreatedon: Ein Datumsfeld, das das Erstellungsdatum des Segments beschreibt.
  • msdynmkt_sourcesegmentcreatedby: Ein Zeichenfolgenfeld, das den Ersteller des Segments beschreibt.

Anmerkung

Das Hinzufügen der Felder msdynmkt_sourcesegmentcreatedon und msdynmkt_sourcesegmentcreatedby ist nicht zwingend erforderlich. Das Segment funktioniert auch ohne diese Felder, aber die beiden Felder werden nicht aufgefüllt, wenn sie nicht zum Datenpaket hinzugefügt werden.

Beispielanforderung


POST <Organization URL>/api/data/v9.0/msdynmkt_segmentdefinitions HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "msdynmkt_segmentquery": "PROFILE(contact).FILTER(ISNOTNULL(address1_county))",
    "statecode": 0,
    "statuscode": 723270001,
    // Separate GUIDs by a comma
    "msdynmkt_includedmembers": "<member GUID>",
    // Separate GUIDs by a comma
    "msdynmkt_excludedmembers": "<member GUID>",
    "msdynmkt_disablesegmentrefresh": false,
    "msdynmkt_segmentrefreshintervalminutes": 15
}

Antwortheader


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: <Organization URL>/api/data/v9.0/msdynmkt_segmentdefinitions(<Segment definition ID>)

Nachdem Sie die Segmentdefinition erstellt haben, müssen Sie die Segmententität erstellen, die mit der Segmentdefinition verknüpfte Details hinzufügt.

Segmententität erstellen

Danach müssen Sie einen neuen Segmententitätsdatensatz erstellen. Wenn Sie die POST-Anforderung der Segmententität an die Dynamics 365 Customer Insights - Journeys-API senden, wird ein neuer Segmententitätsdatensatz in der angegebenen Organisation mit den angegebenen Eigenschaften erstellt. Das neu erstellte Segment kann dann für die gezielte Ausrichtung und Personalisierung von Marketingaktivitäten basierend auf den definierten Kriterien verwendet werden.

POST <Organization URL>/api/data/v9.0/msdynmkt_segments

Die URL für die POST-Anforderung ist <Organization URL>/api/data/v9.0/msdynmkt_segments. Die <Organization URL> ist die Basis-URL für die Customer Insights - Journeys-Organisation, in der die Segmententität erstellt wird.

Nutzdaten

{
    "msdynmkt_displayname": string,
    "msdynmkt_type": number,
    "msdynmkt_source": number,
    "msdynmkt_baseentitylogicalname": string,
    "statecode": number,
    "statuscode": number,
    "msdynmkt_sourcesegmentuid": string,
    "owningbusinessunit@odata.bind": string
}

Beschreibung

Die in den Nutzdaten enthaltenen Eigenschaften sind:

  • msdynmkt_displayname: Eine Zeichenfolge, die den Namen des Segments darstellt.
  • msdynmkt_type: Eine Ganzzahl, die den Typ des Segments darstellt. Der Wert kann einer der folgenden sein:
    • 10 = Statisches Segment
    • 11 = Dynamisches Segment
  • msdynmkt_source: Eine Ganzzahl, die die Quelle des Segments darstellt. Für Customer Insights - Journeys sollte der Wert wie folgt aussehen:
    • 12: Customer Insights - Journeys
  • msdynmkt_baseentitylogicalname: Eine Zeichenfolge, die den Typ des Mitglieds darstellt, das im Segment sein wird.
  • statecode: Ein Integer, der den aktuellen Status des Segments angibt. Der Wert kann einer der folgenden sein:
    • 0 = Aktiv
    • 1 = Inaktiv
  • statuscode: Ein Integer, der den Grund dafür angibt, weshalb das Segment sich in seinem aktuellen Status befindet. Der Wert kann einer der folgenden sein:
    • 1 = Aktiv
    • 2 = Inaktiv (wenn sich die Segmentdefinition im Entwurfsstatus befindet)
    • 3 = Fehler
    • 4 = Gelöscht
    • 5 = Wird exportiert (wenn sich die Segmentdefinition im Veröffentlichungsstatus befindet)
  • msdynmkt_sourcesegmentuid: Eine Zeichenfolge, die den eindeutigen Bezeichner des Segments darstellt, auf dem das aktuelle Segment basiert.
  • owningbusinessunit@odata.bind: (Optional) Eine Zeichenfolge, die den Verweis auf die Geschäftseinheit darstellt, die Eigentümer des Segments ist.

Beispielanforderung


POST <Organization URL>/api/data/v9.0/msdynmkt_segments HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "msdynmkt_displayname": "<display name>",
    "msdynmkt_type": 11,
    "msdynmkt_source": 12,
    // Set to contact, lead, or any custom table that
    // represents the type of member who will be in the segment.
    "msdynmkt_baseentitylogicalname": "contact",
    "statecode": 1,
    // Inactive if segment definition is in Draft state
    // Exporting if segment definition is in Publishing state
    "statuscode": 2,
    "msdynmkt_sourcesegmentuid": "<segment definition ID>",
    // If any (not required)
    "owningbusinessunit@odata.bind": "/businessunits(<BU ID>)",
}

Anmerkung

Zum Veröffentlichungsdatum dieses Artikels unterstützt Customer Insights - Journeys nur Kontakte und Leads.

Antworten


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: <Organization URL>/api/data/v9.0/msdynmkt_segments(<Segment ID>)

Veröffentlichen

Dies ist eine API-Anforderung zum Veröffentlichen einer Marketingsegmentdefinition in Customer Insights - Journeys.

POST <Organization URL>/api/data/v9.0/msdynmkt_PublishSegmentDefinition

Die API-Anforderung wird per HTTP POST an den API-Endpunkt gesendet. Die API-Methode (msdynmkt_PublishSegmentDefinition) ist in der URL angegeben.

Nutzdaten:

{
    "SegmentId": "<Segment ID>"
}

Beschreibung

Die Anforderungsnutzdaten enthalten ein JSON-Objekt, das das Feld „SegmentId“ enthält. Sie müssen <Segment ID> durch die tatsächliche ID des Marketingsegments ersetzen, das Sie veröffentlichen möchten.

Wenn diese Anforderung an den Customer Insights - Journeys-Server gesendet wird, validiert dieser die Nutzdaten und veröffentlicht die angegebene Segmentdefinition, wenn sie gültig ist. Dadurch wird das Segment für den Einsatz in Marketingaktivitäten wie Kundenkontaktverläufe, E-Mail-Kampagnen und Events verfügbar.

Mitglieder anzeigen

Diese API-Anforderung wird verwendet, um die Mitglieder eines Marketingsegments in Customer Insights - Journeys anzuzeigen.

POST: <Organizaiton URL>/api/data/v9.0/msdynmkt_MembersList

Die API-Anforderung wird per HTTP POST an den API-Endpunkt gesendet. Die API-Methode (msdynmkt_MembersList) ist in der URL angegeben.

Nutzdaten

{
    "SegmentId": "<Segment ID>"
}

Beschreibung

Die Anforderungsnutzlast enthält ein JSON-Objekt mit der ID des Segments, dessen Mitglieder Sie anzeigen möchten. Sie müssen <Organization URL> durch die tatsächliche URL Ihrer Customer Insights - Journeys-Organisation und <Segment ID> durch die ID des Segments ersetzen, für das Sie Mitglieder anzeigen möchten.

Wenn die API-Anforderung empfangen wird, validiert sie die Nutzdaten und gibt eine Antwort zurück, die die Liste der Mitglieder für die angegebene Segmentdefinition enthält. Diese API ist nützlich, um Einblicke in die Zusammensetzung eines Segments zu erhalten und etwaige Probleme im Zusammenhang mit der Segmentmitgliedschaft zu beheben.

Die Antwort auf die API-Anfrage enthält ein JSON-Objekt, das die Liste der Mitglieder zusammen mit ihren Details enthält.

Antworten

{
    "@odata.context": "<Organizaiton URL>/api/data/v9.0/$metadata#Microsoft.Dynamics.CRM.msdynmkt_MembersListResponse",
    "StatusCode": 200,
    "ResultText": "{\"baseEntityLogicalName\":\"contact\",\"primaryKeyColumnName\":\"contactid\",\"members\":[\"<member GUID>, <member GUID>"],\"additionalProperties\":{}}"
}