Operaciones básicas en segmentos que utilizan API en marketing saliente

Artículo
01/10/2024

Nota

Dynamics 365 Marketing y Dynamics 365 Customer Insights son ahora Customer Insights - Journeys y Customer Insights - Data. Para obtener más información, consulte Preguntas frecuentes de Dynamics 365 Customer Insights

Los nuevos clientes de Customer Insights - Journeys solo reciben características de recorridos en tiempo real. Para obtener más información, consulte Instalación de recorridos en tiempo real predeterminada.

Importante

Este artículo solo se aplica a marketing saliente, que se eliminará del producto el 30 de junio de 2025. Para evitar interrupciones, realice la transición a viajes en tiempo real antes de esta fecha. Más información: Descripción general de la transició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 Dynamics 365 Customer Insights - Journeys.

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

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.
Si utiliza el alcance de la unidad de negocios, agregar un contacto al que el propietario del segmento no tiene acceso (unidad de negocios) bloqueará el segmento (lo hará inutilizable), así que asegúrese de no agregar contactos de la unidad de negocios incorrecta en su código.
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\"}]"
}

Compartir a través de

Operaciones básicas en segmentos que utilizan API en marketing saliente

Operaciones CRUD en segmentos estáticos

Operaciones CRUD en segmentos dinámicos

Operaciones CRUD en segmentos compuestos

Agregar/quitar contactos en segmentos estáticos

Validación de segmentos

Recursos adicionales