4、租户创建与配置：通过REST API创建租户、设置租户属性、配置默认规则链

在 ThingsBoard 多租户架构中，租户（Tenant）是资源隔离与权限控制的核心单元。本章将演示如何通过 REST API 完成租户的完整生命周期操作：创建租户实体、设置业务属性、绑定默认规则链。掌握这些操作是构建 SaaS 平台管理能力的基础。

4.1 租户创建：REST API 调用流程

ThingsBoard 提供标准的 RESTful 接口用于租户管理。创建租户需要系统管理员（SysAdmin）权限，请求路径为 /api/tenant，使用 POST 方法。请求体为 JSON 格式，包含租户的基本信息。

4.1.1 创建租户请求示例

POST /api/tenant
Content-Type: application/json
Authorization: Bearer ${JWT_TOKEN}

{
  "title": "智联科技集团",
  "email": "admin@zhilian.com",
  "country": "中国",
  "state": "广东省",
  "city": "深圳市",
  "address": "南山区科技园南路1号",
  "address2": "A栋20层",
  "phone": "+86-755-88886666",
  "additionalInfo": {
    "industry": "智能制造",
    "tenantLevel": "enterprise"
  }
}

响应成功时返回 HTTP 201 Created，响应体包含完整的租户对象，其中 id 字段为系统自动生成的 UUID，是后续所有操作（属性设置、规则链绑定）的标识。

4.1.2 关键字段说明

4.2 设置租户属性：扩展业务配置

租户属性（Tenant Attributes）用于存储与业务相关的配置数据，例如：最大设备数限制、数据保留天数、白名单域名、API 调用配额等。属性通过 /api/tenant/{tenantId}/attributes 接口进行管理。

4.2.1 属性设置操作

使用 POST 方法设置租户属性，支持批量写入。属性值可以是字符串、数字、布尔值或 JSON 对象。

POST /api/plugins/telemetry/TENANT/${TENANT_ID}/attributes/SERVER_SCOPE
Content-Type: application/json
Authorization: Bearer ${JWT_TOKEN}

{
  "maxDevices": 5000,
  "dataRetentionDays": 90,
  "allowedDomains": ["zhilian.com", "zl-iot.com"],
  "enableAuditLog": true,
  "dashboardTheme": "dark"
}

4.2.2 常用租户属性清单

4.3 配置默认规则链：租户级规则引擎绑定

每个租户可以绑定一条默认规则链，该规则链将作为该租户下所有新建设备的默认处理流程。配置通过 /api/tenant/{tenantId}/defaultRuleChain 接口完成。

4.3.1 获取规则链 ID

首先通过 /api/ruleChain 接口查询系统中已有的规则链，获取目标规则链的 UUID。

GET /api/ruleChain?pageSize=100&page=0
Authorization: Bearer ${JWT_TOKEN}

响应中查找 name 字段为 "Root Rule Chain" 或自定义规则链名称，记录其 id.id 值。

4.3.2 绑定默认规则链

POST /api/tenant/${TENANT_ID}/defaultRuleChain
Content-Type: application/json
Authorization: Bearer ${JWT_TOKEN}

{
  "defaultRuleChainId": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "entityType": "RULE_CHAIN"
  }
}

4.4 完整操作流程图示

下图展示了从创建租户到绑定默认规则链的完整流程，以及各步骤之间的依赖关系。

4.5 验证配置生效

完成上述步骤后，建议通过以下方式验证配置是否生效：

1. 查询租户详情：调用 GET /api/tenant/{tenantId} 确认租户信息完整。
2. 读取租户属性：调用 GET /api/plugins/telemetry/TENANT/{tenantId}/attributes/SERVER_SCOPE 确认属性已写入。
3. 检查默认规则链：调用 GET /api/tenant/{tenantId}/defaultRuleChain 确认返回的规则链 ID 与绑定的一致。
4. 创建测试设备：在该租户下创建一个新设备，检查其规则链是否自动关联为默认规则链。