使用 Web API 创建 Customer Insights - Journeys 客户细分

使用 Web API，可以：

创建 Customer Insights - Journeys 客户细分。
编辑现有段以添加或删除静态成员，或更改查询定义。
发布客户细分。
查看分段成员。

以下文章演示如何使用 Web API。

创建客户细分定义实体

段定义可以同时包含客户的静态列表和用于选择客户的动态查询。可以创建静态列表、动态查询或静态成员和动态成员的混合体。

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

< 组织 URL> 部分应替换为组织 API 终结点的实际 URL，<SegmentDefinitionID> 应替换为您要更新的客户细分定义的唯一标识符。

有效负载

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

Description

有效负载包含以下属性：

msdynmkt_segmentquery：一个定义用于定义客户细分的查询的字符串。
statecode：一个表示客户细分定义状态的整数值。该值可以为以下任一值：
- 0 = 可用
- 1 = 停用
statuscode：一个表示客户细分定义状态的整数值。该值可以为以下任一值：
- 723270000 = 实时
- 723270001 = 草稿
- 723270002 = 正在生效
- 723270003 = 已删除

msdynmkt_staticlistmembers：应包含在或排除在段中的静态成员组的列表。列表编码为序列化 JSON。列表的每个成员都表示一个静态成员组，并具有以下结构：

{
    groupId: string, // ID of the group as a GUID, which needs to be unique within each segment
    includeType: StaticListIncludeType,
    name: string, // any human-readable name of the group
    inputType: StaticListInputType
}

enum StaticListIncludeType
{
    "Include", // members of this group will always be included in segment members
    "Exclude" // members of this group will always be excluded from segment members
}

enum StaticListInputType
{
    "manualSelect"
}

msdynmkt_disablesegmentrefresh：一个指示是否应禁用自动客户细分刷新的布尔值。
msdynmkt_segmentrefreshintervalminutes：一个以分钟为单位指定刷新间隔的整数值。
msdynmkt_sourcesegmentcreatedon：描述客户细分创建日期的日期字段。
msdynmkt_sourcesegmentcreatedby：描述客户细分创建者的字符串字段。

注释

添加 msdynmkt_sourcesegmentcreatedon 和 msdynmkt_sourcesegmentcreatedby 字段不是必需的。在没有这些字段的情况下，客户细分仍然有效，但如果未添加到有效负载，这两个字段不会填充。

注释

每个段定义实体都可以在字段中最多定义 10 个静态成员组 msdynmkt_staticlistmembers 。

示例请求


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,
    "msdynmkt_staticlistmembers": "[{\"groupId\":\"0f5b0c7f-395d-447b-b14c-315a601f878e\",\"includeType\":\"Include\",\"name\":\"My Include Members Group\",\"inputType\":\"manualSelect\"}]",
    "msdynmkt_disablesegmentrefresh": false,
    "msdynmkt_segmentrefreshintervalminutes": 15
}

响应头


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

创建客户细分定义后，您需要创建客户细分实体，该实体将添加链接到客户细分定义的详细信息。

创建客户细分实体

接下来，您需要创建一个新的客户细分实体记录。当您向 Dynamics 365 Customer Insights - Journeys API 发送客户细分实体 POST 请求时，它将在指定组织中创建一个具有指定属性的新客户细分实体记录。然后，新创建的客户细分可用于根据定义的标准定位和个性化营销活动。

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

POST 请求的 URL 是 <Organization URL>/api/data/v9.0/msdynmkt_segments。 <Organization URL> 是将在其中创建客户细分实体的 Customer Insights - Journeys 组织的基本 URL。

有效负载

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

Description

有效负载中包含的属性是：

msdynmkt_displayname：一个表示客户细分名称的字符串。
msdynmkt_type：一个表示客户细分类型的整数。该值可以为以下任一值：
- 10 = 静态客户细分
- 11 = 动态客户细分
msdynmkt_source：一个表示客户细分来源的整数。对于 Customer Insights - Journeys，值应为以下值：
- 12：Customer Insights - Journeys
msdynmkt_baseentitylogicalname：一个表示将在该客户细分中的成员类型的字符串。
statecode：一个表示客户细分的当前状态的整数。该值可以为以下任一值：
- 0 = 可用
- 1 = 停用
statuscode：一个指示客户细分处于其当前状态的原因的整数。该值可以为以下任一值：
- 1 = 可用
- 2 = 停用（如果客户细分定义处于草稿状态）
- 3 = 错误
- 4 = 已删除
- 5 = 正在导出（如果客户细分定义处于正在发布状态）
msdynmkt_sourcesegmentuid：一个字符串，表示当前客户细分所基于的客户细分的唯一标识符。
owningbusinessunit@odata.bind：（可选）一个字符串，表示对负责该客户细分的业务部门的引用。

示例请求

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

注释

截至本文发布之日，Customer Insights - Journeys 仅支持联系人和潜在顾客。

响应

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

添加静态客户细分成员

对于定义一个或多个静态成员组的段定义，此 API 请求可用于 将成员插入 组。

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

API 请求使用 HTTP POST 发送到 API 终结点。 API 方法 (msdynmkt_AddStaticMembers) 在 URL 中指定。

有效负载

{
    "SegmentId": "<Segment ID>",
    "GroupId": "<Group ID>",
    // at most 1000 entity ids
    "EntityIds": [
      "<Entity ID 1>",
      "<Entity ID 2>",
      ...
    ]
}

注释

每个静态成员组最多可以包含 200,000 个实体 ID。

删除静态客户细分成员

对于定义一个或多个静态成员组的段定义，此 API 请求可用于从组 中删除 成员。

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

API 请求使用 HTTP POST 发送到 API 终结点。 API 方法 (msdynmkt_RemoveStaticMembers) 在 URL 中指定。

有效负载

{
    "SegmentId": "<Segment ID>",
    "GroupId": "<Group ID>",
    "EntityIds": [
      "<Entity ID 1>",
      "<Entity ID 2>",
      ...
    ]
}

查看静态客户细分成员

对于定义一个或多个静态成员组的段定义，此 API 请求可用于 查看组的成员 。

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

API 请求使用 HTTP POST 发送到 API 终结点。 API 方法 (msdynmkt_ListGroupMembers) 在 URL 中指定。

有效负载

{
    "SegmentId": "<Segment ID>",
    "GroupId": "<Group ID>",
    "PageNo": "number", // a number >= 1
    "PageSize": "number" // a number >= 1
}

响应

{
    "@odata.context": "<Organizaiton URL>/api/data/v9.0/$metadata#Microsoft.Dynamics.CRM.msdynmkt_ListGroupMembersResponse",
    "Response": "{\"entityIds\":[\"b1bf9a01-b056-e711-abaa-00155d701c02\",\"b3bf9a01-b056-e711-abaa-00155d701c02\"],\"additionalProperties\":{}}"
}

Publish

这是在 Customer Insights - Journeys 中发布市场营销客户细分定义的 API 请求。

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

API 请求通过 HTTP POST 发送到 API 终结点。 API 方法 (msdynmkt_PublishSegmentDefinition) 在 URL 中指定。

有效负载：

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

Description

请求有效负载包含一个包括“SegmentId”字段的 JSON 对象。您需要将 <Segment ID> 替换为您要发布的市场营销客户细分的实际 ID。

当此请求被发送到 Customer Insights - Journeys 服务器时，它将验证有效负载并发布指定的客户细分定义（如果有效）。这将使该客户细分可用于市场营销活动，例如客户旅程、电子邮件市场活动和活动。

查看成员

此 API 请求用于查看 Customer Insights - Journeys 中市场营销客户细分的成员。

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

API 请求通过 HTTP POST 发送到 API 终结点。 API 方法 (msdynmkt_MembersList) 在 URL 中指定。

有效负载

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

Description

请求有效负载包含一个 JSON 对象，该对象具有要查看其成员的客户细分的 ID。您需要将 <Organization URL> 替换为您的 Customer Insights - Journeys 组织的实际 URL，将 <Segment ID> 替换为您想查看其成员的客户细分的 ID。

收到 API 请求后，系统会验证有效负载并返回一个包含指定客户细分定义的成员列表的响应。此 API 可用于深入了解客户细分的组成并解决与客户细分成员资格相关的任何问题。

对 API 请求的响应将包含一个 JSON 对象，其中包含成员列表及其详细信息。

响应

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

停止一个段落

此 API 请求停止实时段，将其停用，使其不再评估或刷新。

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

有效负载

{
    "SegmentIdList": [
        "<Segment ID 1>",
        "<Segment ID 2>",
        ...
    ]
}

Description

有效载荷包含一个 SegmentIdList 数组，其中包含一个或多个要停止的细分 ID（GUID）。可以在单个请求中停止多个段。某个段落不能被停止的情况是：

当前被一个或多个活跃的旅程使用：响应会指出哪些旅程正在阻塞该分段。
它用作其他活动段中的依赖项：响应指示哪些段正在阻止它。

示例请求

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

{
    "SegmentIdList": ["<Segment ID>"]
}

响应

{
    "summary": "Complete StopSegments operation. Successfully stopped 1 of 1 in total",
    "stopSingleSegmentResults": [
        {
            "SegmentId": "<Segment ID>",
            "WasStopped": true,
            "Message": null,
            "DependentJourneys": null,
            "DependentSegments": null
        }
    ]
}

如果因分段正在使用而无法停止，WasStopped 将为 false，且阻塞的 DependentJourneys 或 DependentSegments 数组将被填充。

Last updated on 2026-05-04

使用 Web API 创建 Customer Insights - Journeys 客户细分

创建客户细分定义实体

有效负载

Description

示例请求

响应头

创建客户细分实体

有效负载

Description

示例请求

响应

添加静态客户细分成员

有效负载

删除静态客户细分成员

有效负载

查看静态客户细分成员

有效负载

响应

Publish

有效负载：

Description

查看成员

有效负载

Description

响应

停止一个段落

有效负载

Description

示例请求

响应

其他资源