Compartir a través de

Crear un segmento de Customer Insights - Journeys mediante la API web

Puede crear un segmento de Customer Insights - Journeys con la API web si sigue el mismo enfoque que usaría para crear cualquier entidad en una Power App. Al crear un segmento de Customer Insights - Journeys, debe crear dos entidades: msdynmkt_segmentdefinitions y msdynmkt_segments. El siguiente artículo muestra cómo crear estas entidades.

Crear una entidad de definición de segmento

La definición de segmento representa un segmento de marketing o una lista de clientes objetivo. Para crear una entidad de definición de segmento, debe enviar una solicitud POST al punto de conexión de API:

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

La parte <URL de la organización> debe reemplazarse con la URL real de la API de la organización punto de conexión y <SegmentDefinitionID> debe reemplazarse con el identificador único de la definición de segmento que desea actualizar.

Carga útil

{
    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
}

Descripción

El objeto de carga contiene las siguientes propiedades:

  • msdynmkt_segmentquery: una cadena que define la consulta utilizada para definir el segmento.
  • statecode: un valor entero que indica el estado de la definición del segmento. El valor puede ser de los siguientes tipos:
    • 0: Activas
    • 1: Inactivas
  • statuscode: un valor entero que indica el estado de la definición del segmento. El valor puede ser de los siguientes tipos:
    • 723270000: Activo
    • 723270001: Borrador
    • 723270002: En proceso de puesta en marcha
    • 723270003: Eliminado
  • msdynmkt_includedmembers: una cadena que contiene una lista de GUID de miembros que deben incluirse en el segmento.
  • msdynmkt_excludedmembers: una cadena que contiene una lista de GUID de miembros que deben excluirse del segmento.
  • msdynmkt_disablesegmentrefresh: un valor booleano que indica si se debe deshabilitar la actualización automática de segmentos.
  • msdynmkt_segmentrefreshintervalminutes: un valor entero que especifica el intervalo de actualización en minutos.
  • msdynmkt_sourcesegmentcreatedon: un campo de fecha para describir la fecha de creación del segmento.
  • msdynmkt_sourcesegmentcreatedby: campo de cadena para describir al creador del segmento.

Nota

No se obligatorio agregar los campos msdynmkt_sourcesegmentcreatedon y msdynmkt_sourcesegmentcreatedby. El segmento sigue funcionando sin estos campos, pero los dos campos no se rellenarán si no se agregan a la carga útil.

Solicitud de ejemplo


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
}

Encabezados de respuesta


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

Después de crear la definición del segmento, deberá crear la entidad del segmento que agregará detalles vinculados a la definición del segmento.

Crear una nueva entidad

A continuación, necesita crear un nuevo registro de entidad del segmento. Cuando envía la solicitud POST de la entidad de segmento a la API de Dynamics 365 Customer Insights - Journeys, se creará un nuevo registro de entidad de segmento en la organización especificada con las propiedades especificadas. El segmento recién creado se puede utilizar para orientar y personalizar las actividades de marketing en función de los criterios definidos.

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

La URL de la solicitud POST es <Organization URL>/api/data/v9.0/msdynmkt_segments. La <Organization URL> es la URL base para la organización de Customer Insights - Journeys donde se creará la entidad de segmento.

Carga útil

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

Descripción

Las propiedades incluidas en la carga son:

  • msdynmkt_displayname: una cadena que representa el nombre del segmento.
  • msdynmkt_type: un número entero que representa el tipo del segmento. El valor puede ser de los siguientes tipos:
    • 10: Segmento estático
    • 11: Segmento dinámico
  • msdynmkt_source: un número entero que representa el origen del segmento. Para Customer Insights - Journeys, el valor debe ser el siguiente:
    • 12: Customer Insights - Journeys
  • msdynmkt_baseentitylogicalname: una cadena que representa el tipo de miembro que estará en el segmento.
  • statecode: un valor entero que indica el estado actual del segmento. El valor puede ser de los siguientes tipos:
    • 0: Activas
    • 1: Inactivas
  • statuscode: un valor entero que indica la razón por la que el segmento está en su estado actual. El valor puede ser de los siguientes tipos:
    • 1: Activas
    • 2: Inactivas (si la definición del segmento está en estado Borrador)
    • 3: Error
    • 4: Eliminado
    • 5: Exportando (si la definición del segmento está en estado Publicando)
  • msdynmkt_sourcesegmentuid: una cadena que representa el identificador único del segmento en el que se basa el segmento actual.
  • owningbusinessunit@odata.bind: (opcional) una cadena que representa la referencia a la unidad de negocio propietaria del segmento.

Solicitud de ejemplo


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>)",
}

Nota

A partir de la fecha de publicación de este artículo, Customer Insights - Journeys solo admite contactos y clientes potenciales.

Respuesta


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

Publicar

Esta es una solicitud de API para publicar una definición de segmento de marketing en Customer Insights - Journeys.

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

La solicitud de API se envía a través de HTTP POST al punto de conexión API. El método API (msdynmkt_PublishSegmentDefinition) se especifica en la URL.

Carga útil:

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

Descripción

La carga útil de la solicitud contiene un objeto JSON que incluye el campo "SegmentId". Debe reemplazar <Segment ID> con el id. real del segmento de marketing que desea publicar.

Cuando esta solicitud se envía al servidor de Customer Insights - Journeys, validará la carga útil y publicará la definición de segmento especificada si es válida. Esto hará que el segmento esté disponible para su uso en actividades de marketing, como recorridos de clientes, campañas de correo electrónico y eventos.

Ver miembros

Esta solicitud de API se usa para ver los miembros de un segmento de marketing en Customer Insights - Journeys.

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

La solicitud de API se envía a través de HTTP POST al punto de conexión API. El método API (msdynmkt_MembersList) se especifica en la URL.

Carga útil

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

Descripción

La carga útil de la solicitud contiene un objeto JSON con el identificador del segmento cuyos miembros desea ver. Debe reemplazar <Organization URL> con la URL real de su organización de Customer Insights - Journeys y <Segment ID> con el id. del segmento para el que desea ver los miembros.

Cuando se recibe la solicitud de API, valida la carga útil y devuelve una respuesta que contiene la lista de miembros para la definición de segmento especificada. Esta API es útil para obtener información sobre la composición de un segmento y para solucionar cualquier problema relacionado con la membresía del segmento.

La respuesta a la solicitud de API incluirá un objeto JSON que contiene la lista de miembros junto con sus detalles.

Respuesta

{
    "@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\":{}}"
}