Operaciones básicas con segmentos mediante la API de segmentación

Un segmento de mercado es la recopilación de contactos a la que se dirige en una campaña de marketing. En algunos casos, se dirigirá a todos los contactos que tenga, pero en la mayoría de los casos, elegirá a quién desea dirigirse en función de los datos demográficos o firmográficos y otras consideraciones. Más información: Trabajar con segmentos.

La API de segmentación permite la interacción mediante programación con registros de segmento. La API de segmentación utiliza la API web estándar de Microsoft Dataverse para manipular entidades o mensajes. Más información: Usar acciones web API de Microsoft Dataverse. Al crear un segmento, las propiedades del segmento se almacenan en la entidad msdyncrm_segment. Puede explorar la información de metadatos de la entidad utilizando @odata.context en la respuesta GET.

Nota

Antes de realizar operaciones debe instalar la aplicación Dynamics 365 Marketing.

En este tema se muestra cómo realizar operaciones básicas con la entidad msdyncrm_segment. Pase los siguientes campos obligatorios para crear un segmento.

Nombre para mostrar Nombre de esquema Valor Obligatorio
Nombre msdyncrm_segmentname Nombre del segmento. Sí.
Tipo de segmento msdyncrm_segmenttype Tipo de segmento. Hay tres tipos de segmentos:
- Estático 192350001
- Dinámico 192350000
- Compuesto 192350002
Sí.
Razón para el estado statuscode Estado actual del segmento. Están disponibles los siguientes códigos de estado:
- Borrador 192350000
- En marcha 192350001
- Detenido 192350002
- En proceso de puesta en marcha 192350006
- Deteniéndose 192350007
Sí.
Consulta de segmento msdyncrm_query Consulta en la consulta de segmentación. Sí (solo con segmentos dinámicos y compuestos).

Para probar las operaciones, puede usar la herramienta Postman. Más información: Usar Postman con la API web.

Operaciones CRUD en segmentos estáticos

Esta sección muestra cómo realizar operaciones CRUD (crear, recuperar, actualizar y eliminar) básicas en segmentos estáticos.

Solicitud de creación

Esta solicitud crea un nuevo segmento estático con dos contactos y statuscode establecido en Draft. El encabezado de respuesta contiene la dirección URL de este registro recién creado (instancia de entidad), que incluye entre paréntesis el identificador único (segmentID) de este registro.

Importante

Debe reemplazar OrgUrl con https://<add your environment name, like ‘myorg.crm’>.dynamics.com. También puede obtener el nombre del entorno de Configuración -> Personalizaciones -> Recursos de desarrollador.

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
}

Importante

El propósito del prefijo crm es indicar el tipo del identificador de registro de forma inequívoca. Esto es necesario cuando se usa una solución de segmentación heredada que usa de manera predeterminada otro tipo de identificador.

Solicitud de actualización

Con la solicitud de actualización, actualiza el statuscode del segmento estático a Going Live (192350006). Cuando se ejecuta la solicitud, actualiza statuscode a Live.

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

Solicitud de recuperación

Con la solicitud de recuperación, recupera todos los segmentos estáticos que se encuentren en el estado Live.

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

También puede recuperar segmentos con propiedades específicas.

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

Solicitud de eliminación

Con la solicitud de eliminación se elimina el segmento estático creado.

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

Operaciones CRUD en segmentos dinámicos

Esta sección muestra cómo realizar operaciones CRUD (crear, recuperar, actualizar y eliminar) básicas en segmentos dinámicos. Los segmentos dinámicos se basan en la consulta de segmento (msdyncrm_segmentquery). Más información: Definición de la consulta de segmento.

Solicitud de creación

Esta solicitud crea un segmento dinámico y establece statuscode en Draft.

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
}

La solicitud siguiente crea un segmento dinámico con una consulta de segmento condicional para recuperar solamente los contactos que tienen el campo address1_city establecido en NewYork o NewJersey.

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
}

La siguiente solicitud crea un nuevo segmento dinámico y establece statuscode en Going Live.

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
}

Solicitud de actualización

Con la solicitud de actualización se actualiza el estado del segmento dinámico a Going Live.

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

Nota

Se recomienda no mover los segmentos directamente al estado Live.

Solicitud de recuperación

Con la solicitud de recuperación, recupera todos los segmentos dinámicos que se encuentren en el estado Stop.

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

Solicitud de eliminación

Con la solicitud de eliminación se elimina el segmento dinámico creado.

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

Operaciones CRUD en segmentos compuestos

Esta sección muestra cómo realizar operaciones CRUD (crear, recuperar, actualizar y eliminar) básicas en segmentos compuestos.

Solicitud de creación

Esta solicitud crea un segmento compuesto y establece statuscode en Going Live.

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
}

Solicitud de actualización

Con la solicitud de actualización se actualiza el estado del segmento compuesto a Stopping.

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

Nota

Se recomienda no mover los segmentos directamente al estado Stopped.

Solicitud de recuperación

Con la solicitud de recuperación, recupera todos los segmentos compuestos que se encuentren en el estado Stop.

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

Solicitud de eliminación

Con la solicitud de eliminación se elimina el segmento compuesto creado.

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

Agregar/quitar contactos en segmentos estáticos

En los segmentos se pueden agregar o quitar miembros de segmentos estáticos de contactos. Puede agregar/quitar contactos proporcionando una definición de consulta o proporcionando identificadores de contacto específicos.

Estos son algunos de los aspectos importantes que hay que tener en cuenta al realizar operaciones de adición/eliminación con miembros del segmento:

  • Solo se pueden agregar o quitar como miembros del tipo de entidad Contacto.
  • Si los id. de contacto proporcionados no existen, se ignoran.
  • Las solicitudes para agregar/eliminar miembros se procesan de forma asincrónica.
  • Puede agregar/eliminar contactos invocando el punto de conexión varias veces, generalmente en lotes de hasta 20 000 contactos cada vez.

Agregar miembros de segmento proporcionando el id.

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\"]"
}

Quitar miembros de segmento proporcionando el id.

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\"]"
}

Agregar miembros de segmento proporcionando una consulta

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

Quitar miembros de segmento proporcionando una consulta

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

Obtener el estado de las operaciones pendientes

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

Recuperar los miembros de segmento (recomendado)

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
}

Importante

En el ejemplo anterior, reemplace SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc con el nombre de su segmento en el back-end, como está en el campo msdyncrm_segmentqueryname de su segmento. Si su segmento tiene el id ce97cb9d-bd75-ea11-a811-000d3a8e8fcc, ese valor será SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc.

Recuperar miembros de segmento (en desuso)

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>

Validación de segmentos

Antes de crear o modificar un segmento, puede comprobar la nueva definición con un punto de conexión de validación dedicado. El punto de conexión devuelve siempre un mensaje de aceptación de estado HTTP y un objeto con una propiedad ValidationResult que contiene una matriz de errores.

En el caso de una definición válida, la matriz de resultados se muestra vacía. De lo contrario, contiene registros para los problemas identificados. La definición del segmento se valida en la creación del registro y el código de estado se establece en En proceso de puesta en marcha.

La validación se salta forma intencionada cuando un segmento se crea en estado Borrador. También una validación fallida da lugar a un error HTTP 400, con un mensaje en el cuerpo de la respuesta.

Validación de una definición de segmento válida

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

Respuesta

{
…
    "ValidationResult": "[]"
}

Validación de una definición de segmento no válida

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

Respuesta

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