操作工厂数据

你可以通过 MQTT 和 API 操作 UNS 数据。

MQTT

MQTT 客户端可以使用 Tier0 生成的凭据连接到 UNS broker。

注意

你可以使用 MQTTX、MQTT Explorer 和 Node-RED 等 MQTT 客户端连接 UNS broker，并发布/订阅消息。

生成 MQTT 凭据

在 Tier0 的 Edge 页签创建新的凭据，并记录下来。

连接 MQTT 客户端

提示

以下客户端作为示例，用来展示如何使用凭据连接 UNS broker。

MQTTX

1. 安装并打开 MQTTX。
2. 使用 Tier0 UNS broker 信息和生成的凭据添加连接。

   {
     "Host": "mqtt.tier0.dev",
     "Port": 8883,
     "Client ID": "<generated client ID>",
     "Username": "<generated username>",
     "Password": "<generated password>"
   }

MQTT Explorer

1. 安装并打开 MQTT Explorer。
2. 使用 broker 信息和生成的凭据添加新连接。

   {
     "Protocol": "mqtt://",
     "Host": "mqtt.tier0.dev",
     "Port": 8883,
     "Username": "<generated username>",
     "Password": "<generated password>"
   }

3. 连接前，在 ADVANCED 中将 client ID 改为凭据 ID。

Node-RED

• 使用 事件流程 - Tier0 中基于 Node-RED 的数据处理模块。
  1. 在 事件流程 中创建数据流，并用 mqtt in 节点作为起点。
  2. 在节点中选择 UNS broker 作为 Server（与 flow 同名），并将 Topic 设置为 UNS 模型。
• 使用独立 Node-RED 实例
  1. 安装并打开 Node-RED 实例。
  2. 在 mqtt in 节点中使用以下信息添加 server。

  {
    {/* under Connection */}
    "Server": "mqtt://mqtt.tier0.dev",
    "Port": 8883,
    "Client ID": "<generated clientId>",
    {/* under Security */}
    "Username": "<generated username>",
    "Password": "<generated password>"
  }

测试连接

1. 确认 client 状态正常。
2. 复制一个 UNS 模型 topic，并通过 client 向它发布一条 message。

API

使用 REST API 操作 UNS 数据。

如何使用 API

OpenAPI base path 是 /openapi/v1，例如 https://your-workspace.tier0.app/openapi/v1，API key 通过 x-api-key header 传入。

获取 API Key

API keys 位于 Settings > API Keys。不同 account type 允许创建的 key type 不同。

• Service Key：只能由 Admin 和 Owner 创建。
• Personal Key：任何人都可以创建，permission scope 与该 account 相同。

Key permission vs Account permission

Account permission 优先于 key permission。即使 key permission 设置为 Full Access，account 无权访问的数据仍然无法通过该 key 访问。

示例

• /uns/create

  创建 UNS path 或 topic。使用 namespace 定义 node tree.

  JavaScript

  const BASE_URL = process.env.TIER0_BASE_URL;
  const API_KEY = process.env.TIER0_API_KEY;
  
  const response = await fetch(`${BASE_URL}/uns/create`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      namespace: [
        {
          name: 'DemoFactory',
          type: 'PATH',
          children: [
            {
              name: 'Site_01',
              type: 'PATH',
              children: [
                {
                  name: 'Production',
                  type: 'PATH',
                  children: [
                    {
                      name: 'Produced_Qty',
                      type: 'TOPIC',
                      topicType: 'METRIC',
                      displayName: 'Produced Quantity',
                      description: 'Produced quantity from the production line.',
                      enableHistory: true,
                      fields: [
                        { name: 'value', type: 'DOUBLE', unit: 'pcs' },
                      ],
                    },
                  ],
                },
              ],
            },
          ],
        },
      ],
    }),
  });
  
  const result = await response.json();
  console.log(result.data.results);

  Python

  import os
  import requests
  
  base_url = os.environ["TIER0_BASE_URL"]
  api_key = os.environ["TIER0_API_KEY"]
  
  response = requests.post(
      f"{base_url}/uns/create",
      headers={"x-api-key": api_key},
      json={
          "namespace": [
              {
                  "name": "DemoFactory",
                  "type": "PATH",
                  "children": [
                      {
                          "name": "Site_01",
                          "type": "PATH",
                          "children": [
                              {
                                  "name": "Production",
                                  "type": "PATH",
                                  "children": [
                                      {
                                          "name": "Produced_Qty",
                                          "type": "TOPIC",
                                          "topicType": "METRIC",
                                          "displayName": "Produced Quantity",
                                          "description": "Produced quantity from the production line.",
                                          "enableHistory": True,
                                          "fields": [
                                              {"name": "value", "type": "DOUBLE", "unit": "pcs"},
                                          ],
                                      },
                                  ],
                              },
                          ],
                      },
                  ],
              },
          ],
      },
      timeout=30,
  )
  response.raise_for_status()
  
  result = response.json()
  print(result["data"]["results"])

  cURL

  curl -X POST "$TIER0_BASE_URL/uns/create" \
    -H "content-type: application/json" \
    -H "x-api-key: $TIER0_API_KEY" \
    -d '{
      "namespace": [
        {
          "name": "DemoFactory",
          "type": "PATH",
          "children": [
            {
              "name": "Site_01",
              "type": "PATH",
              "children": [
                {
                  "name": "Production",
                  "type": "PATH",
                  "children": [
                    {
                      "name": "Produced_Qty",
                      "type": "TOPIC",
                      "topicType": "METRIC",
                      "displayName": "Produced Quantity",
                      "description": "Produced quantity from the production line.",
                      "enableHistory": true,
                      "fields": [
                        { "name": "value", "type": "DOUBLE", "unit": "pcs" }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }'

• /uns/read

  读取一个或多个 UNS topics 的最新值和元数据。

  JavaScript

  const BASE_URL = process.env.TIER0_BASE_URL;
  const API_KEY = process.env.TIER0_API_KEY;
  
  const response = await fetch(`${BASE_URL}/uns/read`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      topics: [
        'DemoFactory/Site_01/Production/Produced_Qty',
      ],
      include_leaf_value: true,
      include_metadata: true,
    }),
  });
  
  const result = await response.json();
  console.log(result.data.results);

  Python

  import os
  import requests
  
  base_url = os.environ["TIER0_BASE_URL"]
  api_key = os.environ["TIER0_API_KEY"]
  
  response = requests.post(
      f"{base_url}/uns/read",
      headers={"x-api-key": api_key},
      json={
          "topics": [
              "DemoFactory/Site_01/Production/Produced_Qty",
          ],
          "include_leaf_value": True,
          "include_metadata": True,
      },
      timeout=30,
  )
  response.raise_for_status()
  
  result = response.json()
  print(result["data"]["results"])

  cURL

  curl -X POST "$TIER0_BASE_URL/uns/read" \
    -H "content-type: application/json" \
    -H "x-api-key: $TIER0_API_KEY" \
    -d '{
      "topics": [
        "DemoFactory/Site_01/Production/Produced_Qty"
      ],
      "include_leaf_value": true,
      "include_metadata": true
    }'

• /uns/update

  通过 path 更新 UNS 节点。使用 updateMask 指定需要变更的字段。

  JavaScript

  const BASE_URL = process.env.TIER0_BASE_URL;
  const API_KEY = process.env.TIER0_API_KEY;
  
  const response = await fetch(`${BASE_URL}/uns/update`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      path: 'DemoFactory/Site_01/Production/Produced_Qty',
      displayName: 'Produced Quantity',
      description: 'Updated production output quantity.',
      updateMask: ['displayName', 'description'],
    }),
  });
  
  const result = await response.json();
  console.log(result.data);

  Python

  import os
  import requests
  
  base_url = os.environ["TIER0_BASE_URL"]
  api_key = os.environ["TIER0_API_KEY"]
  
  response = requests.post(
      f"{base_url}/uns/update",
      headers={"x-api-key": api_key},
      json={
          "path": "DemoFactory/Site_01/Production/Produced_Qty",
          "displayName": "Produced Quantity",
          "description": "Updated production output quantity.",
          "updateMask": ["displayName", "description"],
      },
      timeout=30,
  )
  response.raise_for_status()
  
  result = response.json()
  print(result["data"])

  cURL

  curl -X POST "$TIER0_BASE_URL/uns/update" \
    -H "content-type: application/json" \
    -H "x-api-key: $TIER0_API_KEY" \
    -d '{
      "path": "DemoFactory/Site_01/Production/Produced_Qty",
      "displayName": "Produced Quantity",
      "description": "Updated production output quantity.",
      "updateMask": ["displayName", "description"]
    }'

• /uns/delete

  删除一个或多个 UNS 模型。使用 hard_delete: false 将模型移到回收站。

  JavaScript

  const BASE_URL = process.env.TIER0_BASE_URL;
  const API_KEY = process.env.TIER0_API_KEY;
  
  const response = await fetch(`${BASE_URL}/uns/delete`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      topics: [
        'DemoFactory/Site_01/Production/Produced_Qty',
      ],
      hard_delete: false,
    }),
  });
  
  const result = await response.json();
  console.log(result.data);

  Python

  import os
  import requests
  
  base_url = os.environ["TIER0_BASE_URL"]
  api_key = os.environ["TIER0_API_KEY"]
  
  response = requests.post(
      f"{base_url}/uns/delete",
      headers={"x-api-key": api_key},
      json={
          "topics": [
              "DemoFactory/Site_01/Production/Produced_Qty",
          ],
          "hard_delete": False,
      },
      timeout=30,
  )
  response.raise_for_status()
  
  result = response.json()
  print(result["data"])

  cURL

  curl -X POST "$TIER0_BASE_URL/uns/delete" \
    -H "content-type: application/json" \
    -H "x-api-key: $TIER0_API_KEY" \
    -d '{
      "topics": [
        "DemoFactory/Site_01/Production/Produced_Qty"
      ],
      "hard_delete": false
    }'

API 参考

• Tier0 OpenAPI 参考

下一步

• 在 UNS 上构建应用 — 使用 UNS 数据构建工业应用。
• 分析 UNS 数据 — 使用 Marimo Notebook 和 Python 分析 UNS 数据。