Categories

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();
$categoryApi = $api->newApi("categories", $auth, $apiUrl);

Get Category

<?php

//...
$category = $categoryApi->get($id);

{
  "category":{
    "id":221,
    "title":"test",
    "alias":"test4",
    "description":null,
    "color":null,
    "bundle":"asset"
  }
}

通过 ID 获取单个分类。

HTTP 请求

GET /categories/ID

响应

预期响应代码：200

请参阅 JSON 代码示例。

分类属性

名称	类型	描述
`id`	int	分类的 ID
`isPublished`	boolean	分类发布的状态
`dateAdded`	`datetime`	分类创建的日期/时间
`createdBy`	int	创建分类的用户 ID
`createdByUser`	string	创建分类用户的姓名
`dateModified`	datetime/null	分类修改的日期/时间
`modifiedBy`	int	最后修改分类的用户 ID
`modifiedByUser`	string	最后修改分类用户的姓名
`title`	string	分类的标题
`alias`	string	分类别名
`description`	string	分类描述
`color`	string	分类颜色
`bundle`	string	分类所在的包

List Contact Categories

<?php

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

返回用户可用的联系人分类列表。此列表不可过滤。

HTTP 请求

GET /categories

响应

预期响应代码: 200

{
  "total":8,
  "categories":[
    {
      "id":1,
      "title":"Bold",
      "alias":"bold",
      "description":null,
      "color":"b36262",
      "bundle":"point"
    },
  ]
}

分类属性

名称	类型	描述
`id`	int	分类的 ID
`isPublished`	boolean	分类的发布状态
`dateAdded`	`datetime`	分类创建的日期/时间
`createdBy`	int	创建分类的用户 ID
`createdByUser`	string	创建分类用户的姓名
`dateModified`	datetime/null	分类修改的日期/时间
`modifiedBy`	int	最后修改分类的用户 ID
`modifiedByUser`	string	最后修改分类用户的姓名
`title`	string	分类的标题
`alias`	string	分类的别名
`description`	string	分类的描述
`color`	string	分类的颜色
`bundle`	string	分类所在的包

创建分类

<?php

$data = array(
    'categoryname' => 'test',
    'categoryemail' => 'test@example.com',
    'categorycity' => 'Raleigh',
);

$category = $categoryApi->create($data);

创建新的分类。

HTTP 请求

POST /categories/new

POST 参数

名称	类型	描述
`title`	string	分类的标题
`bundle`	string	分类所在的包

响应

预期响应代码: 201

属性

与获取分类中的相同。

编辑分类

<?php

$id   = 1;
$data = array(
    'title' => 'test',
    'bundle' => 'asset'
);

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

$category = $categoryApi->edit($id, $data, $createIfNotFound);

编辑新的分类。请注意，这支持 PUT 或 PATCH，具体取决于所需的行为。

PUT 如果给定的 ID 不存在，则会创建一个分类，并清除所有分类信息，然后添加来自请求的信息。 PATCH 如果具有给定 ID 的分类不存在，则会失败，并且使用来自请求的值更新分类字段值。

HTTP 请求

要编辑一个分类，并在未找到该分类时返回 404：

PATCH /categories/ID/edit

要编辑一个分类，并在找不到该分类时创建一个新的分类：

PUT /categories/ID/edit

POST 参数

Name	Type	Description
title	string	分类标题
bundle	string	该分类所在的包

响应

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

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

属性

与 Get Category 相同。

删除分类

<?php

$category = $categoryApi->delete($id);

删除一个分类。

HTTP 请求

DELETE /categories/ID/delete

响应

Expected Response Code: 200

属性

与 Get Category 相同。

分配分类

要将一个分类分配给一个实体，请在 payload 中设置 category = [ID]。例如，以下是如何将分类 123 分配给一个新的 Asset：

$data = array(
    'title' => 'PDF sent as a API request',
    'storageLocation' => 'remote',
    'file' => 'https://www.mautic.org/media/logos/logo/Mautic_Logo_DB.pdf'
    'category' => 123
);

$asset = $assetApi->create($data);

该分类必须存在于 Mautic 实例中，并且该实体必须支持分类。