本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 裝置佈建 MQTT API
<a name="fleet-provision-api"></a><a name="provision-mqtt-api"></a>

機群佈建服務支援下列 MQTT API 操作：
+ `CreateCertificateFromCsr`
+ `CreateKeysAndCertificate`
+ `RegisterThing`

這個 API 支援 Concise Binary Object Representation (CBOR) 格式和 JavaScript 物件標記法 (JSON) 的回應緩衝區，具體取決於主題的*承載格式*而定。為了清楚起見，本節中的回應和請求範例會以 JSON 格式顯示。


| *承載格式* | 回應格式資料類型 | 
| --- | --- | 
| cbor | Concise Binary Object Representation (CBOR) | 
| json | JavaScript 物件標記法 (JSON) | 

**重要**  
發佈請求訊息主題之前，請先訂閱回應主題以接收回應。此 API 使用的訊息使用 MQTT 的發佈/訂閱通訊協定，以提供請求和回應互動。  
如果您在發佈請求*之前*未訂閱回應主題，則可能不會收到該請求的結果。  
IoT Core Fleet Provisioning 透過用於發佈 API 請求的相同 MQTT 連線，傳回裝置佈建 MQTT API 結果。

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

從憑證簽署請求 (CSR) 建立憑證。 AWS IoT 提供由 Amazon 根憑證授權機構 (CA) 簽署的用戶端憑證。新憑證的狀態為 `PENDING_ACTIVATION`。當您呼叫 `RegisterThing` 以使用此憑證佈建實物時，憑證狀態會變更為 `INACTIVE` 或 `ACTIVE`，如範本中所述。

如需有關使用憑證授權單位憑證和憑證簽署請求建立用戶端憑證的詳細資訊，請參閱 [使用您的憑證授權機構憑證建立用戶端憑證](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` 以使用此憑證佈建實物時，憑證狀態會變更為 `INACTIVE` 或 `ACTIVE`，如範本中所述。

**注意**  
為了安全起見，由 `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`  
用來證明憑證擁有權的權杖。 AWS IoT 當您透過 MQTT 建立憑證時， 會產生權杖。

`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`  
佈建期間建立的 IoT 物件名稱。

### 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`  
錯誤訊息。