本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# CodeBuild 的建置通知範例
Amazon CloudWatch Events 具有 的內建支援 AWS CodeBuild。CloudWatch Events 是描述 AWS 資源變更的系統事件串流。使用 CloudWatch Events，您可以撰寫宣告規則，將感興趣的事件與要採取的自動化動作建立關聯。此範例使用 Amazon CloudWatch Events 和 Amazon Simple Notification Service (Amazon SNS)，每當組建成功、失敗、從一個組建階段移至另一個組建階段，或這些事件的任意組合時，就會傳送組建通知給訂閱者。
**重要**
執行此範例可能會導致 AWS 您的帳戶產生費用。這包括 CodeBuild 以及與 Amazon CloudWatch 和 Amazon SNS 相關的 AWS 資源和動作的可能費用。如需詳細資訊，請參閱 [CodeBuild 定價](https://aws.amazon.com/codebuild/pricing)、[Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing)和 [Amazon SNS 定價](https://aws.amazon.com/sns/pricing)。
**Topics**
+ [執行建置通知範例](#sample-build-notifications-running)
+ [建置通知輸入格式參考](sample-build-notifications-ref.md)
## 執行建置通知範例
使用下列程序來執行建置通知範例。
**如何執行此範例**
1. 如果您已在 Amazon SNS 中設定並訂閱要用於此範例的主題，請跳到步驟 4。否則，如果您使用 IAM 使用者而非 AWS 根帳戶或管理員使用者來使用 Amazon SNS，請將下列陳述式 （介於 *\$1\$1\$1 BEGIN ADDING STATEMENT HERE \$1\$1\$1 *和 *\$1\$1\$1 END ADDING STATEMENT HERE \$1\$1\$1* 之間） 新增至使用者 （或使用者相關聯的 IAM 群組）。不建議使用 AWS 根帳戶。此陳述式可讓您檢視、建立、訂閱和測試 Amazon SNS 中主題的通知傳送。省略符號 (`...`) 用於簡化和協助您找到新增陳述式的位置。請不要移除任何陳述式，也不要在現有政策中輸入這些省略符號。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sns:CreateTopic",
"sns:GetTopicAttributes",
"sns:List*",
"sns:Publish",
"sns:SetTopicAttributes",
"sns:Subscribe"
],
"Resource": "*"
}
]
}
```
------
**注意**
修改此政策的 IAM 實體必須在 IAM 中具有修改政策的許可。
如需詳細資訊，請參閱[《IAM 使用者指南》中的編輯客戶受管政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console)或「編輯或刪除群組、使用者或角色的內嵌政策」一節[中的使用內嵌政策 （主控台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console)。 **
1. 在 Amazon SNS. AWS CodeBuild uses CloudWatch Events 中建立或識別主題，以透過 Amazon SNS 傳送建置通知至此主題。
建立主題：
1. 開啟位於 https：//[https://console.aws.amazon.com/sns](https://console.aws.amazon.com/sns) 的 Amazon SNS 主控台。
1. 請選擇**建立主題**。
1. 在 **Create new topic (建立新主題)** 中，針對 **Topic name (主題名稱)**，輸入主題的名稱 (例如 **CodeBuildDemoTopic**)。(如果您選擇其他名稱，請在此範例中全部換成此名稱。)
1. 請選擇**建立主題**。
1. 在**主題詳細資訊：CodeBuildDemoTopic** 頁面上，複製**主題 ARN** 值。您在下一個步驟中需要使用到此數值。
![\[主題 ARN 值。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/topic-arn.png)
如需詳細資訊，請參閱《*Amazon SNS 開發人員指南*》中的[建立主題](https://docs.aws.amazon.com/sns/latest/dg/CreateTopic.html)。
1. 讓一或多個收件人訂閱主題來接收電子郵件通知。
讓收件人訂閱主題：
1. 從上一個步驟開啟 Amazon SNS 主控台後，在導覽窗格中，選擇**訂閱**，然後選擇**建立訂閱**。
1. 在 **Create subscription (建立訂閱)** 中，對於 **Topic ARN (主題 ARN)**，貼上您從上個步驟複製的主題 ARN。
1. 對於**通訊協定**，選擇**電子郵件**。
1. 針對 **Endpoint (端點)**，輸入收件人的完整電子郵件地址。
![\[訂閱組態。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/create-subscription.png)
1. 選擇 **Create Subscription** (建立訂閱)。
1. Amazon SNS 會傳送訂閱確認電子郵件給收件人。若要開始接收電子郵件通知，收件人必須選擇訂閱確認電子郵件中的 **Confirm subscription (確認訂閱)** 連結。收件人按一下連結後，如果成功訂閱，Amazon SNS 會在收件人的 Web 瀏覽器中顯示確認訊息。
如需詳細資訊，請參閱《*Amazon SNS 開發人員指南*》中的[訂閱主題](https://docs.aws.amazon.com/sns/latest/dg/SubscribeTopic.html)。
1. 如果您使用 使用者而非 AWS 根帳戶或管理員使用者來使用 CloudWatch Events，請將下列陳述式 （介於 *\$1\$1\$1 BEGIN ADDING STATEMENT HERE \$1\$1\$1* 和 *\$1\$1\$1 END ADDING STATEMENT HERE \$1\$1\$1* 之間） 新增至使用者 （或使用者相關聯的 IAM 群組）。不建議使用 AWS 根帳戶。此陳述式用於允許使用者使用 CloudWatch Events。省略符號 (`...`) 用於簡化和協助您找到新增陳述式的位置。請不要移除任何陳述式，也不要在現有政策中輸入這些省略符號。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"events:*",
"iam:PassRole"
],
"Resource": "arn:aws:iam::*:role/Service*"
}
]
}
```
------
**注意**
修改此政策的 IAM 實體必須在 IAM 中具有修改政策的許可。
如需詳細資訊，請參閱[《IAM 使用者指南》中的編輯客戶受管政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console)或「編輯或刪除群組、使用者或角色的內嵌政策」一節[中的使用內嵌政策 （主控台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console)。 **
1. 在 CloudWatch Events 中建立規則。若要這樣做，請開啟 CloudWatch 主控台，網址為 https：//[https://console.aws.amazon.com/cloudwatch](https://console.aws.amazon.com/cloudwatch)。
1. 在導覽窗格中，在 **Events (事件)** 下方選擇 **Rules (規則)**，然後選擇 **Create rule (建立規則)**。
1. 在 **Step 1: Create rule page (步驟 1：建立規則頁面)** 上，應該已選取 **Event Pattern (事件模式)** 和 **Build event pattern to match events by service (建構事件的模式，依服務來匹配事件)**。
1. 針對**服務名稱**，選擇 **CodeBuild**。在 **Event Type (事件類型)** 中，應該已選取 **All Events (所有事件)**。
1. 下列程式碼應顯示於 **Event Pattern Preview (事件模式預覽)** 中：
```
{
"source": [
"aws.codebuild"
]
}
```
1. 選擇 **Edit (編輯)**，將 **Event Pattern Preview (事件模式預覽)** 中的程式碼換成下列兩個規則模式之一。
AWS CodeBuild中指定的建置專案有建置開始或完成時，這第一個規則模式就會觸發事件。
```
{
"source": [
"aws.codebuild"
],
"detail-type": [
"CodeBuild Build State Change"
],
"detail": {
"build-status": [
"IN_PROGRESS",
"SUCCEEDED",
"FAILED",
"STOPPED"
],
"project-name": [
"my-demo-project-1",
"my-demo-project-2"
]
}
}
```
在上個規則中，依需要進行下列程式碼變更。
+ 若要在有建置開始或完成時觸發事件，請保留 `build-status` 陣列中所示的所有值，或移除整個 `build-status` 陣列。
+ 若只要在組建完成時才觸發事件，請從 `build-status` 陣列中移除 `IN_PROGRESS`。
+ 若只要在組建開始時才觸發事件，請從 `build-status` 陣列中移除所有值，但保留 `IN_PROGRESS`。
+ 若要對所有組建專案觸發事件，請移除整個 `project-name` 陣列。
+ 若只要對個別組建專案觸發事件，請在 `project-name` 陣列中指定每個組建專案的名稱。
每當 AWS CodeBuild中指定的建置專案有建置從一個建置階段進入另一個建置階段時，這第二個規則模式就會觸發事件。
```
{
"source": [
"aws.codebuild"
],
"detail-type": [
"CodeBuild Build Phase Change"
],
"detail": {
"completed-phase": [
"SUBMITTED",
"PROVISIONING",
"DOWNLOAD_SOURCE",
"INSTALL",
"PRE_BUILD",
"BUILD",
"POST_BUILD",
"UPLOAD_ARTIFACTS",
"FINALIZING"
],
"completed-phase-status": [
"TIMED_OUT",
"STOPPED",
"FAILED",
"SUCCEEDED",
"FAULT",
"CLIENT_ERROR"
],
"project-name": [
"my-demo-project-1",
"my-demo-project-2"
]
}
}
```
在上個規則中，依需要進行下列程式碼變更。
+ 若要在每次建置階段變更時觸發事件 (對每個建置，最多可傳送九次通知)，請保留 `completed-phase` 陣列中所示的所有值，或移除整個 `completed-phase` 陣列。
+ 若只要對個別組建階段變更來觸發事件，請在 `completed-phase` 陣列中移除您不想觸發事件的每個組建階段的名稱。
+ 若要在每次組建階段狀態變更時觸發事件，請保留 `completed-phase-status` 陣列中所示的全部值，或移除整個 `completed-phase-status` 陣列。
+ 若只要對個別組建階段狀態變更來觸發事件，請在 `completed-phase-status` 陣列中移除您不想觸發事件的每個組建階段狀態的名稱。
+ 若要對所有組建專案觸發事件，請移除 `project-name` 陣列。
+ 若要對個別組建專案觸發事件，請在 `project-name` 陣列中指定每個組建專案的名稱。
如需事件模式的詳細資訊，請參閱《Amazon EventBridge 使用者指南》中的[事件模式](https://docs.aws.amazon.com/eventbridge/latest/userguide/filtering-examples-structure.html)。
如需使用事件模式進行篩選的詳細資訊，請參閱《Amazon EventBridge 使用者指南》中的[使用事件模式進行內容型篩選](https://docs.aws.amazon.com/eventbridge/latest/userguide/content-filtering-with-event-patterns.html)。
**注意**
如果希望建置狀態變更和建置階段變更都觸發事件，您必須建立兩個不同的規則：一個用於建置狀態變更，另一個用於建置階段變更。如果您嘗試將兩個規則合併成單一規則，合併的規則可能產生非預期的結果，或完全停止運作。
完成取代程式碼時，選擇 **Save (儲存)**。
1. 在 **Targets** (目標) 中，選擇 **Add target (新增目標)**。
1. 在目標清單中，選擇 **SNS topic (SNS 主題)**。
1. 對於 **Topic (主題)**，選擇您稍早識別或建立的主題。
1. 展開 **Configure input (設定輸入)**，然後選擇 **Input Transformer (輸入轉換器)**。
1. 在 **Input Path (輸入路徑)** 方塊中，輸入下列其中一個輸入路徑。
如果規則的 `detail-type` 值為 `CodeBuild Build State Change`，請輸入下列程式碼。
```
{"build-id":"$.detail.build-id","project-name":"$.detail.project-name","build-status":"$.detail.build-status"}
```
如果規則的 `detail-type` 值為 `CodeBuild Build Phase Change`，請輸入下列程式碼。
```
{"build-id":"$.detail.build-id","project-name":"$.detail.project-name","completed-phase":"$.detail.completed-phase","completed-phase-status":"$.detail.completed-phase-status"}
```
如需其他類型的資訊，請參閱[建置通知輸入格式參考](sample-build-notifications-ref.md)。
1. 在 **Input Template (輸入範本)** 方塊中，輸入下列其中一個輸入範本。
如果規則的 `detail-type` 值為 `CodeBuild Build State Change`，請輸入下列程式碼。
```
"Build '' for build project '' has reached the build status of ''."
```
如果規則的 `detail-type` 值為 `CodeBuild Build Phase Change`，請輸入下列程式碼。
```
"Build '' for build project '' has completed the build phase of '' with a status of ''."
```
1. 選擇**設定詳細資訊**。
1. 在 **Step 2: Configure rule details (步驟 2：設定規則詳細資訊)** 頁面上，輸入名稱和選填的描述。針對 **State (狀態)**，將 **Enabled (啟用)** 保留為選取狀態。
1. 選擇**建立規則**。
1. 建立組建專案、執行組建，以及檢視組建資訊。
1. 確認 CodeBuild 現在已成功傳送建置通知。例如，檢查您的收件匣中是否有組建通知電子郵件。
若要變更規則的行為，請在 CloudWatch 主控台中選擇您要變更的規則，選擇**動作**，然後選擇**編輯**。變更規則，選擇 **Configure details (設定詳細資訊)**，然後選擇 **Update rule (更新規則)**。
若要停止使用規則來傳送建置通知，請在 CloudWatch 主控台中選擇您要停止使用的規則，選擇**動作**，然後選擇**停用**。
若要完全刪除規則，請在 CloudWatch 主控台中選擇您要刪除的規則，選擇**動作**，然後選擇**刪除**。
# 建置通知輸入格式參考
CloudWatch 會以 JSON 格式傳送通知。
組建狀態變更通知採用以下格式：
```
{
"version": "0",
"id": "c030038d-8c4d-6141-9545-00ff7b7153EX",
"detail-type": "CodeBuild Build State Change",
"source": "aws.codebuild",
"account": "123456789012",
"time": "2017-09-01T16:14:28Z",
"region": "us-west-2",
"resources":[
"arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX"
],
"detail":{
"build-status": "SUCCEEDED",
"project-name": "my-sample-project",
"build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX",
"additional-information": {
"artifact": {
"md5sum": "da9c44c8a9a3cd4b443126e823168fEX",
"sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX",
"location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip"
},
"environment": {
"image": "aws/codebuild/standard:5.0",
"privileged-mode": false,
"compute-type": "BUILD_GENERAL1_SMALL",
"type": "LINUX_CONTAINER",
"environment-variables": []
},
"timeout-in-minutes": 60,
"build-complete": true,
"initiator": "MyCodeBuildDemoUser",
"build-start-time": "Sep 1, 2017 4:12:29 PM",
"source": {
"location": "codebuild-123456789012-input-bucket/my-input-artifact.zip",
"type": "S3"
},
"logs": {
"group-name": "/aws/codebuild/my-sample-project",
"stream-name": "8745a7a9-c340-456a-9166-edf953571bEX",
"deep-link": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logEvent:group=/aws/codebuild/my-sample-project;stream=8745a7a9-c340-456a-9166-edf953571bEX"
},
"phases": [
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:12:29 PM",
"end-time": "Sep 1, 2017 4:12:29 PM",
"duration-in-seconds": 0,
"phase-type": "SUBMITTED",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:12:29 PM",
"end-time": "Sep 1, 2017 4:13:05 PM",
"duration-in-seconds": 36,
"phase-type": "PROVISIONING",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:05 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 4,
"phase-type": "DOWNLOAD_SOURCE",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 0,
"phase-type": "INSTALL",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 0,
"phase-type": "PRE_BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 70,
"phase-type": "BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 0,
"phase-type": "POST_BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 0,
"phase-type": "UPLOAD_ARTIFACTS",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:26 PM",
"duration-in-seconds": 4,
"phase-type": "FINALIZING",
"phase-status": "SUCCEEDED"
},
{
"start-time": "Sep 1, 2017 4:14:26 PM",
"phase-type": "COMPLETED"
}
]
},
"current-phase": "COMPLETED",
"current-phase-context": "[]",
"version": "1"
}
}
```
組建階段變更通知採用以下格式：
```
{
"version": "0",
"id": "43ddc2bd-af76-9ca5-2dc7-b695e15adeEX",
"detail-type": "CodeBuild Build Phase Change",
"source": "aws.codebuild",
"account": "123456789012",
"time": "2017-09-01T16:14:21Z",
"region": "us-west-2",
"resources":[
"arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX"
],
"detail":{
"completed-phase": "COMPLETED",
"project-name": "my-sample-project",
"build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX",
"completed-phase-context": "[]",
"additional-information": {
"artifact": {
"md5sum": "da9c44c8a9a3cd4b443126e823168fEX",
"sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX",
"location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip"
},
"environment": {
"image": "aws/codebuild/standard:5.0",
"privileged-mode": false,
"compute-type": "BUILD_GENERAL1_SMALL",
"type": "LINUX_CONTAINER",
"environment-variables": []
},
"timeout-in-minutes": 60,
"build-complete": true,
"initiator": "MyCodeBuildDemoUser",
"build-start-time": "Sep 1, 2017 4:12:29 PM",
"source": {
"location": "codebuild-123456789012-input-bucket/my-input-artifact.zip",
"type": "S3"
},
"logs": {
"group-name": "/aws/codebuild/my-sample-project",
"stream-name": "8745a7a9-c340-456a-9166-edf953571bEX",
"deep-link": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logEvent:group=/aws/codebuild/my-sample-project;stream=8745a7a9-c340-456a-9166-edf953571bEX"
},
"phases": [
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:12:29 PM",
"end-time": "Sep 1, 2017 4:12:29 PM",
"duration-in-seconds": 0,
"phase-type": "SUBMITTED",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:12:29 PM",
"end-time": "Sep 1, 2017 4:13:05 PM",
"duration-in-seconds": 36,
"phase-type": "PROVISIONING",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:05 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 4,
"phase-type": "DOWNLOAD_SOURCE",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 0,
"phase-type": "INSTALL",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 0,
"phase-type": "PRE_BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 70,
"phase-type": "BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 0,
"phase-type": "POST_BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 0,
"phase-type": "UPLOAD_ARTIFACTS",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:26 PM",
"duration-in-seconds": 4,
"phase-type": "FINALIZING",
"phase-status": "SUCCEEDED"
},
{
"start-time": "Sep 1, 2017 4:14:26 PM",
"phase-type": "COMPLETED"
}
]
},
"completed-phase-status": "SUCCEEDED",
"completed-phase-duration-seconds": 4,
"version": "1",
"completed-phase-start": "Sep 1, 2017 4:14:21 PM",
"completed-phase-end": "Sep 1, 2017 4:14:26 PM"
}
}
```