本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 设备预调配 MQTT API
<a name="fleet-provision-api"></a><a name="provision-mqtt-api"></a>

实例集预调配服务支持以下 MQTT API 操作：
+ `CreateCertificateFromCsr`
+ `CreateKeysAndCertificate`
+ `RegisterThing`

此 API 支持简明二进制对象表示 (CBOR) 格式和 JavaScript 对象表示法 (JSON) 的响应缓冲区，具体取决于*payload-format*主题。为了清楚起见，本节中的响应和请求示例以 JSON 格式显示。


| *payload-format* | 响应格式数据类型 | 
| --- | --- | 
| cbor | 简洁二进制对象表示法 (CBOR) | 
| json | JavaScript 对象表示法 (JSON) | 

**重要**  
在发布请求消息主题之前，请订阅响应主题以接收响应。此 API 使用的消息使用 MQTT 的发布/订阅协议来提供请求和响应交互。  
如果您未在发布请求*之前*订阅响应主题，则无法收到该请求的结果。  
IoT Core 实例集配置通过用于发布 API 请求的同一 MQTT 连接返回设备配置 MQTT API 结果。

## CreateCertificateFromCsr
<a name="create-cert-csr"></a>

根据证书签名请求 (CSR) 创建证书。 AWS IoT 提供由 Amazon 根证书颁发机构 (CA) 签署的客户证书。新证书的状态为 `PENDING_ACTIVATION`。当您调用 `RegisterThing` 使用此证书预调配事物时，证书状态将如模板中所述，更改为 `ACTIVE` 或 `INACTIVE`。

有关使用证书颁发机构证书和证书签名请求来创建客户端证书的更多信息，请参阅[使用您的 CA 证书创建客户端证书](create-device-cert.md)。

**注意**  
为了安全起见，`CreateCertificateFromCsr` 返回的 `certificateOwnershipToken` 会在一小时后过期。必须在 `certificateOwnershipToken` 过期前调用 `RegisterThing`。如果由 `CreateCertificateFromCsr` 创建的证书尚未激活，并且在令牌过期时尚未附加到策略或事物，则该证书将被删除。如果令牌过期，设备可以调用 `CreateCertificateFromCsr` 以生成新证书。

### CreateCertificateFromCsr 请求
<a name="create-cert-csr-request"></a>

发布包含 `$aws/certificates/create-from-csr/payload-format` 主题的消息。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

#### CreateCertificateFromCsr 请求有效载荷
<a name="create-cert-csr-request-payload"></a>

```
{
    "certificateSigningRequest": "string"
}
```

`certificateSigningRequest`  
CSR，采用 PEM 格式。

### CreateCertificateFromCsr 响应
<a name="create-cert-csr-response"></a>

订阅 `$aws/certificates/create-from-csr/payload-format/accepted`。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

#### CreateCertificateFromCsr 响应有效载荷
<a name="create-cert-csr-response-payload"></a>

```
{
    "certificateOwnershipToken": "string",
    "certificateId": "string",
    "certificatePem": "string"
}
```

`certificateOwnershipToken`  
在预调配期间证明证书所有权的令牌。

`certificateId`  
证书的 ID。证书管理操作仅接受 certificateId。

`certificatePem`  
PEM 格式的证书数据。

### CreateCertificateFromCsr 错误
<a name="create-cert-csr-error"></a>

要接收错误响应，请订阅 `$aws/certificates/create-from-csr/payload-format/rejected`。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

#### CreateCertificateFromCsr 错误有效载荷
<a name="create-cert-csr-error-payload"></a>

```
{
    "statusCode": int,
    "errorCode": "string",
    "errorMessage": "string"
}
```

`statusCode`  
状态代码。

`errorCode`  
错误代码。

`errorMessage`  
错误消息。

## CreateKeysAndCertificate
<a name="create-keys-cert"></a>

创建新密钥和证书。 AWS IoT 提供由 Amazon 根证书颁发机构 (CA) 签署的客户证书。新证书的状态为 `PENDING_ACTIVATION`。当您调用 `RegisterThing` 使用此证书预调配事物时，证书状态将如模板中所述，更改为 `ACTIVE` 或 `INACTIVE`。

**注意**  
为了安全起见，`CreateKeysAndCertificate` 返回的 `certificateOwnershipToken` 会在一小时后过期。必须在 `certificateOwnershipToken` 过期前调用 `RegisterThing`。如果由 `CreateKeysAndCertificate` 创建的证书尚未激活，并且在令牌过期时尚未附加到策略或事物，则该证书将被删除。如果令牌过期，设备可以调用 `CreateKeysAndCertificate` 以生成新证书。

### CreateKeysAndCertificate 请求
<a name="create-keys-cert-request"></a>

在 `$aws/certificates/create/payload-format` 上发布带有空消息有效载荷的消息。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

### CreateKeysAndCertificate 响应
<a name="create-keys-cert-response"></a>

订阅 `$aws/certificates/create/payload-format/accepted`。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

#### CreateKeysAndCertificate 响应
<a name="create-keys-cert-response-payload"></a>

```
{
    "certificateId": "string",
    "certificatePem": "string",
    "privateKey": "string",
    "certificateOwnershipToken": "string"
}
```

`certificateId`  
证书 ID。

`certificatePem`  
PEM 格式的证书数据。

`privateKey`  
私有密钥。

`certificateOwnershipToken`  
在预调配期间证明证书所有权的令牌。

### CreateKeysAndCertificate 错误
<a name="create-keys-cert-error"></a>

要接收错误响应，请订阅 `$aws/certificates/create/payload-format/rejected`。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

#### CreateKeysAndCertificate 错误有效载荷
<a name="create-keys-cert-error-payload"></a>

```
{
    "statusCode": int,
    "errorCode": "string",
    "errorMessage": "string"
}
```

`statusCode`  
状态代码。

`errorCode`  
错误代码。

`errorMessage`  
错误消息。

## RegisterThing
<a name="register-thing"></a>

使用预定义的模板预调配事物。

### RegisterThing 请求
<a name="register-thing-request"></a>

在 `$aws/provisioning-templates/templateName/provision/payload-format` 上发布消息。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

`templateName`  
预调配模板名称。

#### RegisterThing 请求有效载荷
<a name="register-thing-request-payload"></a>

```
{
    "certificateOwnershipToken": "string",
    "parameters": {
        "string": "string",
        ...
    }
}
```

`certificateOwnershipToken`  
证明证书所有权的令牌。当您通过 MQTT 创建证书时， AWS IoT 会生成令牌。

`parameters`  
可选。来自设备的键/值对由[预先预调配挂钩](pre-provisioning-hook.md)用于评估注册请求。

### RegisterThing 响应
<a name="register-thing-response"></a>

订阅 `$aws/provisioning-templates/templateName/provision/payload-format/accepted`。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

`templateName`  
预调配模板名称。

#### RegisterThing 响应有效载荷
<a name="register-thing-response-payload"></a>

```
{
    "deviceConfiguration": {
        "string": "string",
        ...
    },
    "thingName": "string"
}
```

`deviceConfiguration`  
在模板中定义的设备配置。

`thingName`  
预调配期间创建的物联网事物的名称。

### RegisterThing 错误响应
<a name="register-thing-error"></a>

要接收错误响应，请订阅 `$aws/provisioning-templates/templateName/provision/payload-format/rejected`。

`payload-format`  
消息负载格式为 `cbor` 或 `json`。

`templateName`  
预调配模板名称。

#### RegisterThing 错误响应有效负载
<a name="register-thing-error-payload"></a>

```
{
    "statusCode": int,
    "errorCode": "string",
    "errorMessage": "string"
}
```

`statusCode`  
状态代码。

`errorCode`  
错误代码。

`errorMessage`  
错误消息。