Fields

Note

此页面的内容需要进行重大更新。旧页面包含过时且可能不准确的信息。您仍然可以通过 Mautic Developer Documentation archived repository 访问它。

如果您有兴趣帮助开发此页面和其他新内容的，请考虑加入文档编写工作。

请阅读 Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始您的贡献。

使用此端点来处理 Mautic 的联系人/公司字段。

使用 Mautic API 库

您可以通过以下方式使用 Mautic API Library 与此 API 进行交互，或者可以使用本文档中描述的各种 HTTP 端点。

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth = new ApiAuth();
$auth     = $initAuth->newAuth($settings);
$apiUrl   = "https://example.com";
$api      = new MauticApi();
$assetApi = $api->newApi("assets", $auth, $apiUrl);

// 获取联系人字段上下文：
$fieldApi = $api->newApi("contactFields", $auth, $apiUrl);

// 或者使用 'companyFields' 来获取公司字段：
$fieldApi = $api->newApi("companyFields", $auth, $apiUrl);

获取字段

<?php

//...
$field = $fieldApi->get($id);

获取单个字段，通过 ID。

HTTP 请求

GET /fields/contact/ID 或 GET /fields/company/ID

响应

Expected Response Code: 200

{
  "field":{
    "isPublished":true,
    "dateAdded":"2016-11-10T13:02:52+00:00",
    "createdBy":1,
    "createdByUser":"Sharru-Ukin Kumar",
    "dateModified":null,
    "modifiedBy":null,
    "modifiedByUser":null,
    "id":165,
    "label":"API test field",
    "alias":"api_test_field11",
    "type":"text",
    "group":null,
    "order":36,
    "object":"lead",
    "defaultValue":null,
    "isRequired":false,
    "isPubliclyUpdatable":false,
    "isUniqueIdentifier":0,
    "properties":[]
  }
}

字段属性

- Name
  - Type
  - Description
- - id
  - int
  - 字段的 ID
- - isPublished
  - boolean
  - 是否可使用
- - publishUp
  - datetime/null
  - 字段开始生效的日期和时间
- - publishDown
  - datetime/null
  - 字段失效的日期和时间
- - dateAdded
  - datetime
  - 字段创建的日期和时间
- - createdBy
  - int
  - 创建该字段的用户 ID
- - createdByUser
  - string
  - 创建该字段用户的姓名
- - dateModified
  - datetime/null
  - 字段修改的日期和时间
- - modifiedBy
  - int
  - 最后修改该字段的用户 ID
- - modifiedByUser
  - string
  - 最后修改该字段用户的姓名
- - label
  - string
  - 字段名称
- - alias
  - string
  - 字段的唯一别名，用于表单字段名称属性
- - description
  - string/null
  - 字段描述
- - type
  - string
  - 字段类型
- - group
  - string
  - 字段所属的组
- - order
  - int
  - 字段的排序号
- - object
  - string
  - 使用该字段的对象，可以是 Contact 或 Company
- - defaultValue
  - string
  - 字段的默认值
- - isRequired
  - boolean
  - 如果为 true，则表示该字段是必填项
- - isPubliclyUpdatable
  - boolean
  - 如果为 true，则表示公共请求可以更改该字段的值，例如跟踪像素查询
- - isUniqueIdentifier
  - boolean
  - 如果为 true，则表示该字段是唯一标识符，因此如果此字段的值相同，则应合并联系人
- - properties
  - array
  - 字段选项，如果字段类型需要的话。

列出联系人字段

<?php

//...
$fields = $fieldApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

{

“total”:71, “fields”:[

{
“isPublished”:true, “dateAdded”:”2016-10-12T11:31:13+00:00”, “createdBy”:1, “createdByUser”:”Judith Czinege”, “dateModified”:”2016-10-12T11:31:30+00:00”, “modifiedBy”:1, “modifiedByUser”:”Judith Czinege”, “id”:100, “label”:”Multiselect test”, “alias”:”multiselect_test”, “type”:”multiselect”, “group”:”core”, “order”:3, “object”:”lead”, “defaultValue”:null, “isRequired”:false, “isPubliclyUpdatable”:false, “isUniqueIdentifier”:false, “properties”:{

“list”:[

{
“label”:”PHP”, “value”:”php”

}, {

“label”:”JS”, “value”:”js”

}, {

“label”:”English”, “value”:”en”

}

]

}

},

]

}

查询参数

名称	描述
`search`	用于过滤实体的字符串或搜索命令
`start`	返回实体的起始行，默认为 0
`limit`	要返回的实体数量限制，默认为分页系统的配置 - 默认为 30
`orderBy`	用于排序的列，可以使用响应中列出的任何列
`orderByDir`	排序方向：`asc` 或 `desc`
`publishedOnly`	仅返回当前可用的实体
`minimal`	仅返回实体数组，不包含其他列表

HTTP 请求

GET /fields/contact 或 GET /fields/company

响应

预期响应代码: 200

请参阅 JSON 代码示例。

字段属性

- Name
  - Type
  - Description
- - id
  - int
  - ID of the field
- - isPublished
  - boolean
  - Availability for use
- - publishUp
  - datetime/null
  - Field available from date/time
- - publishDown
  - datetime/null
  - Field unavailable from date/time
- - dateAdded
  - datetime
  - Field creation date/time
- - createdBy
  - int
  - ID of the User that created the field
- - createdByUser
  - string
  - Name of the User that created the field
- - dateModified
  - datetime/null
  - Field modified date/time
- - modifiedBy
  - int
  - ID of the User that last modified the field
- - modifiedByUser
  - string
  - Name of the User that last modified the field
- - label
  - string
  - Name of the field
- - alias
  - string
  - Unique alias of the field used in the Form Field name attributes
- - description
  - string/null
  - Description of the field
- - type
  - string
  - Field type
- - group
  - string
  - Group of the fields where the field belongs
- - order
  - int
  - Order number of the field
- - object
  - string
  - Which object uses the fieldContact or Company
- - defaultValue
  - string
  - Default value of the field
- - isRequired
  - boolean
  - true if this is a required field
- - isPubliclyUpdatable
  - boolean
  - true if public requests can change the field value - the tracking pixel query for example
- - isUniqueIdentifier
  - boolean
  - true if the field is a unique identifier therefore Contacts should merge if the value of this field is the same
- - properties
  - array
  - Field options if the field type needs some

Create field

<?php

$data = array(
    'label' => 'API test field',
    'type' => 'text',
);

$field = $fieldApi->create($data);

Multiselect field

<?php

$data = array(
    'label' => 'API test field',
    'type' => 'multiselect',
    'isPubliclyUpdatable' => true,
    'properties' => array(
       'list' => array(
          array(
            'label' => 'label 1',
            'value' => 'value 1'
          ),
          array(
            'label' => 'label 2',
            'value' => 'value 2'
          )
        )
    )
);

$field = $fieldApi->create($data);

Create a new field.

HTTP Request

POST /fields/contact/new or POST /fields/company/new

POST parameters

- Name
  - Type
  - Description
- - label
  - string
  - 字段名称
- - alias
  - string
  - 字段的唯一别名，用于表单字段名称属性
- - description
  - string/null
  - 字段描述
- - type
  - string
  - 字段类型
- - group
  - string
  - 字段所属的组
- - order
  - int
  - 字段的排序号
- - object
  - string
  - 使用该字段的对象，可以是 Contact 或 Company
- - defaultValue
  - string
  - 字段的默认值
- - isRequired
  - boolean
  - 如果是必填字段，则为 true
- - isPubliclyUpdatable
  - boolean
  - 如果允许公开请求修改该字段的值（例如跟踪像素查询），则为 true
- - isUniqueIdentifier
  - boolean
  - 如果该字段是唯一标识符，并且如果此字段的值相同，则应合并联系人记录，则为 true
- - properties
  - array
  - 字段选项，如果字段类型需要某些选项时使用

Response

Expected Response Code: 201

Properties

同 Get Field。

编辑字段

<?php

$id   = 1;
$data = array(
    'label' => 'API test field',
    'type' => 'text',
);

// 如果未找到 ID 为 1 的字段，则创建新字段？
$createIfNotFound = true;

$field = $fieldApi->edit($id, $data, $createIfNotFound);

编辑现有字段。该功能支持 PUT 或 PATCH 方法，具体取决于所需的行为。

PUT 如果给定 ID 不存在，则会创建一个字段。 PATCH 如果找不到具有给定 ID 的字段，则会失败，并且使用请求中的值更新字段的值。

HTTP 请求

要编辑一个字段并返回 404（如果未找到该字段）：

PATCH /fields/contact/ID/edit 或 PATCH /fields/company/ID/edit

要编辑一个字段，如果未找到该字段，则创建一个新字段：

PUT /fields/contact/ID/edit 或 PUT /fields/company/ID/edit

POST 参数

- Name
  - Type
  - Description
- - label
  - string
  - 字段名称
- - alias
  - string
  - 用于表单字段名称属性的唯一别名
- - description
  - string/null
  - 字段描述
- - type
  - string
  - 字段类型
- - group
  - string
  - 字段所属组
- - order
  - int
  - 字段排序号
- - object
  - string
  - 使用该字段的对象，可以是 Contact 或 Company
- - defaultValue
  - string
  - 字段的默认值
- - isRequired
  - boolean
  - 如果是必填字段，则为 true
- - isPubliclyUpdatable
  - boolean
  - 如果允许公开请求修改该字段的值（例如跟踪像素查询），则为 true
- - isUniqueIdentifier
  - boolean
  - 如果该字段是唯一标识符，并且如果此字段的值相同，则应合并联系人记录，则为 true
- - properties
  - array
  - 如果字段类型需要某些选项，则为字段选项。

Response

如果使用 PUT，预期的响应代码是 ``200``（编辑字段）或 ``201``（创建字段）。

如果使用 PATCH，预期的响应代码是 200。

Properties

同 Get Field。

删除字段

<?php

$field = $fieldApi->delete($id);

删除一个字段。

HTTP Request

DELETE /fields/contact/ID/delete 或 DELETE /fields/company/ID/delete

Note

如果该字段正在被某个 Segment 使用，则无法删除它。这将返回 HTTP 409 (Conflict) 响应。在删除字段之前，请将其从任何 Segment 过滤器中移除。

Response

预期的响应代码: 200

如果字段正在使用的响应代码: 409

Properties

同 Get Field。