# 实例元数据

> 读取运行机器与进程元数据、Provision 版本信息，以及自定义公开实例字段。

Source: https://console.getchrovia.com/zh/docs/sdk-instance-metadata

**能力：**`instanceMetadata`。**API：**`chrovia.instanceMetadata`，是对象，不是函数或 Promise。在 Provision Service Worker 使用；页面访问还需要 `unrestrictedApi`。

## 添加公开字段

运行机器字段由浏览器采集。应用自有元数据放在 `internal.instance_metadata.public` 下：

```json
{
  "internal": {
    "instance_metadata": {
      "public": {
        "instance_id": "workspace-01",
        "label": "Workspace 01",
        "region": "test"
      }
    }
  }
}
```

启动前按要求合并并签名 [EP](https://console.getchrovia.com/zh/docs/sdk-extended-preferences)。应用的 `public.instance_id` 不是内核租约的 `instanceId`，不会改变租约身份。

```js
const metadata = globalThis.chrovia?.instanceMetadata;
if (metadata) {
  console.log({
    label: metadata.public?.label,
    pid: metadata.process?.id,
    packageVersion: metadata.provision?.manifest?.version,
  });
}
```

## 对象结构

| 部分 | 字段 |
| --- | --- |
| `host` | `machineId`、`serialNumber`、`hostname`、`userName` |
| `os` | `name`、`version`、`architecture` |
| `hardware` | `logicalProcessors`、`physicalMemory`（字节） |
| `directories` | `userData`、`downloads`、`desktop`、`appData`、`localAppData`、`home`、`temp` |
| `process` | `id`，浏览器进程 ID |
| `provision` | Provision 根目录的 `manifest` |
| `public` | 配置的 JSON 对象 |

不可用或为空的值及部分会被省略。使用可选访问，不要假设所有平台都有序列号或 `localAppData`。即使拥有能力，元数据不可用时也可能为 `undefined`。

## 边界

这是运行机器信息，不是由 `fingerprint_override` 生成的指纹身份。`directories.downloads` 报告平台默认下载路径，不一定是 Profile 实际配置的保存位置。设置下载行为应使用 [Profile 偏好](https://console.getchrovia.com/zh/docs/sdk-extended-preferences)，而不是修改元数据。

主机标识和文件路径属于敏感信息。`public` 表示可暴露的数据，不适合存放令牌或密码。更改配置后重启；修改返回的 JS 对象不是持久化写入 API。