**支援結束通知：**2026 年 10 月 30 日， AWS 將結束對 Amazon Pinpoint 的支援。2026 年 10 月 30 日之後，您將無法再存取 Amazon Pinpoint 主控台或 Amazon Pinpoint 資源 (端點、區段、行銷活動、旅程和分析)。如需詳細資訊，請參閱 [Amazon Pinpoint 終止支援](https://docs.aws.amazon.com/console/pinpoint/migration-guide)。**注意：**與 SMS、語音、行動推播、OTP 和電話號碼驗證相關的 APIs 不受此變更影響，並受 AWS 最終使用者傳訊支援。

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

# 教學課程
<a name="tutorials"></a>

本節的教學課程，旨在向 Amazon Pinpoint 新使用者說明如何完成幾項重要任務。如果您不熟悉 Amazon Pinpoint，或者只是不熟悉某些功能，這些教學課程是個不錯的起點。

此指南中的教學任務是以開發人員或系統管理員為目標對象。這些教學課程說明如何使用 Amazon Pinpoint API、 AWS SDKs和 來執行任務 AWS CLI。

**Topics**
+ [將 Postman 與 Amazon Pinpoint 一起使用](tutorials-using-postman.md)
+ [設定簡訊註冊系統](tutorials-two-way-sms.md)

# 教學課程：將 Postman 與 Amazon Pinpoint API 搭配使用
<a name="tutorials-using-postman"></a>

Postman 是一種熱門工具，用於在簡單易用的圖形環境中測試 API。您可以使用 Postman 來傳送 API 請求至任何 REST API，以及接收對您請求的回應。若要測試並疑難排解您對 Amazon Pinpoint API 的呼叫，使用 Postman 是方便的作法。本教學課程包括設定 Postman，以及將 Postman 與 Amazon Pinpoint 搭配使用的程序。

**注意**  
Postman 是由第三方公司開發。它並非由 Amazon Web Services 開發或支援 (AWS)。若要進一步了解如何使用 Postman 或需 Postman 相關問題的協助，請參閱 Postman 網站的[支援中心](https://support.postman.com/hc/en-us)。

## 關於本教學
<a name="tutorials-using-postman-about"></a>

本節包含此教學的概觀。

**目標對象**  
本教學是專為開發人員和系統實作者而制定。您不需要熟悉 Amazon Pinpoint 或 Postman，也可完成本教學課程的步驟。您應該能夠輕鬆管理 IAM 政策和修改 JSON 程式碼範例。

本教學課程的程序，旨在防止新使用者使用會永久刪除 Amazon Pinpoint 資源的 API 操作。進階使用者可以修改與 使用者關聯的政策來移除此限制。

**使用的功能**  
本教學課程包含以下 Amazon Pinpoint 功能的使用範例：
+ 使用 Postman 與 Amazon Pinpoint API 互動

**所需時間**  
此教學課程需約 15 分鐘完成。

**區域限制**  
使用此解決方案時，沒有區域限制。

**資源用量成本**  
建立 AWS 帳戶無需付費。不過，透過實作此解決方案，如果您使用 Postman 執行下列任何操作，可能會產生 AWS 使用成本：
+ 傳送電子郵件、簡訊、行動推播，或是語音訊息
+ 建立和傳送行銷活動
+ 使用電話號碼驗證功能

如需深入了解使用 Amazon Pinpoint 的相關費用，請參閱 [Amazon Pinpoint 定價](https://aws.amazon.com/pinpoint/pricing/)。

# 搭配 Amazon Pinpoint 使用 Postman 的先決條件
<a name="tutorials-using-postman-prerequisites"></a>

開始本教學課程之前，請先完成下列先決條件：
+ 您必須擁有 AWS 帳戶。若要建立 AWS 帳戶，請前往 [https://console.aws.amazon.com/](https://console.aws.amazon.com/)：//www.** AWS **。
+ 請確定您用來登入 的帳戶 AWS 管理主控台 可以建立新的 IAM 政策和角色。
+ 確認您至少建立了一個範例專案，該專案要開啟電子郵件，且有個已驗證的電子郵件身分。請參閱 *Amazon Pinpoint 使用者指南*中的[使用電子郵件支援建立 Amazon Pinpoint 專案](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-setup-create.html)。
+ 請確定您擁有 AWS 帳戶 ID。您可以在主控台的右上角找到 AWS 您的帳戶 ID，也可以使用命令列界面 (CLI)。請參閱[尋找 AWS 您的帳戶 ID](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html#FindAccountId)。
+ 您必須在電腦下載並安裝 Postman。您可以從 [Postman 網站](https://www.getpostman.com)下載 Postman。
+ 在電腦安裝 Postman 後，建立一個 Postman 帳戶。首次啟動 Postman 應用程式時，系統會提示您登入或建立新帳戶。按照 Postman 提供的說明登入帳戶，或建立帳戶 (如果您沒有帳戶的話)。

**下一步**：[建立 IAM 政策及角色](tutorials-using-postman-iam-user.md)

# 建立與 Amazon Pinpoint 搭配使用的 IAM 政策和角色
<a name="tutorials-using-postman-iam-user"></a>

若使用 Postman 測試 Amazon Pinpoint API，第一步就是建立使用者。本節中，您需要建立一個政策，讓使用者能與所有 Amazon Pinpoint 資源互動。然後建立一個使用者，並直接連接政策。

## 建立 IAM 政策
<a name="tutorials-using-postman-iam-user-create-policy"></a>

了解如何建立 IAM 政策。使用此政策的使用者和角色，可以與 Amazon Pinpoint API 中的所有資源互動。此外還讓您存取與 Amazon Pinpoint 電子郵件 API 相關聯的資源，以及 Amazon Pinpoint SMS 和語音 API。

**建立政策**

1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在導覽窗格中，選擇**政策**，然後選擇**建立政策**。

1. 在**政策編輯器**中，選取 **JSON**。刪除**政策編輯器**中任何最新的 JSON，使其空白。將下列 JSON 複製並貼到**政策編輯器**中，然後在**政策編輯器**中以您的 AWS 帳戶 ID 取代 *123456789012* 的所有執行個體。

   您可以在主控台的右上角找到您的 AWS 帳戶 ID，也可以使用 CLI，請參閱[尋找 AWS 您的帳戶 ID](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html#FindAccountId)。
**注意**  
為了保護您 Amazon Pinpoint 帳戶中的資料，此政略只包含允許您讀取、建立和修改資源的許可。它不包含允許您刪除資源的許可。您可以使用 IAM 主控台中的視覺化編輯器修改此政策。詳情請參閱 IAM 使用者指南中的[管理 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html)。您也可以使用 IAM API 中的 [CreatePolicyVersion](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreatePolicyVersion.html) 操作，更新此政策。  
除了 `mobiletargeting` 服務之外，此政策另包含允許您與 `ses` 和 `sms-voice` 服務互動的許可。`ses` 和 `sms-voice` 許可讓您分別與 Amazon Pinpoint Email API 和 Amazon Pinpoint SMS 和語音 API 互動。這些 `mobiletargeting` 許可可讓您與 Amazon Pinpoint API 互動。

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": [
                   "mobiletargeting:Update*",
                   "mobiletargeting:Get*",
                   "mobiletargeting:Send*",
                   "mobiletargeting:Put*",
                   "mobiletargeting:Create*"
               ],
               "Resource": [
                   "arn:aws:mobiletargeting:*:123456789012:apps/*",
                   "arn:aws:mobiletargeting:*:123456789012:apps/*/campaigns/*",
                   "arn:aws:mobiletargeting:*:123456789012:apps/*/segments/*"
               ]
           },
           {
               "Sid": "VisualEditor1",
               "Effect": "Allow",
               "Action": [
                   "mobiletargeting:TagResource",
                   "mobiletargeting:PhoneNumberValidate",
                   "mobiletargeting:ListTagsForResource",
                   "mobiletargeting:CreateApp"
               ],
               "Resource": "arn:aws:mobiletargeting:*:123456789012:*"
           },
           {
               "Sid": "VisualEditor2",
               "Effect": "Allow",
               "Action": [
                   "ses:TagResource",
                   "ses:Send*",
                   "ses:Create*",
                   "ses:Get*",
                   "ses:List*",
                   "ses:Put*",
                   "ses:Update*",
                   "sms-voice:SendVoiceMessage",
                   "sms-voice:List*",
                   "sms-voice:Create*",
                   "sms-voice:Get*",
                   "sms-voice:Update*"
               ],
               "Resource": "*"
           }
       ]
   }
   ```

------

   選擇**下一步**。

1. 針對**政策名稱**，輸入政策的名稱，例如 **PostmanAccessPolicy**。選擇**建立政策**。

1. (選用) 選取**新增標籤**，可將標籤加入政策。

1. 選擇下**一步：檢閱**。

## 建立 IAM 使用者
<a name="tutorials-using-postman-iam-user-create-user"></a>

**警告**  
IAM 使用者具有長期憑證，這會造成安全風險。為了協助降低此風險，建議您只為這些使用者提供執行任務所需的許可，並在不再需要這些使用者時將其移除。

建立政策後，您可以建立一個使用者並連接政策。建立使用者時，IAM 會為您提供一組允許 Postman 執行 Amazon Pinpoint API 操作的憑證。

**建立使用者**

1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在 IAM 主控台的導覽窗格中，選擇**使用者**，然後選擇**建立使用者**。

1. 在**使用者詳細資訊**下，在**使用者名稱**中輸入可識別使用者帳戶的名稱，例如 **PostmanUser**。然後選擇**下一步**。

1. 在**設定許可**下，為**許可選項**選擇**直接連接政策**。

1. 在**許可政策**下，選擇您在[建立 IAM 政策中建立的政策 ](#tutorials-using-postman-iam-user-create-policy)(**PostmanAccessPolicy**)。然後選擇**下一步**。

1. 您可以在**檢閱和建立**頁面上，新增能幫助您識別使用者的標籤 (選用)。如需使用標籤的詳細資訊，請參閱 *IAM 使用者指南*中的[標記 IAM 資源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)。

1. 當您準備好建立使用者，請選擇 **Create user (建立使用者)**。

## 建立存取金鑰
<a name="tutorials-using-postman-iam-user-create-key"></a>

**警告**  
此種情況需要具備程式化存取權限且擁有長期憑證的 IAM 使用者，此舉將構成安全風險。為了協助降低此風險，建議您只為這些使用者提供執行任務所需的許可，並在不再需要這些使用者時將其移除。必要時可以更新存取金鑰。如需詳細資訊，請參閱《IAM 使用者指南》**中的[更新存取金鑰](https://docs.aws.amazon.com/IAM/latest/UserGuide/id-credentials-access-keys-update.html)。

 IAM 提供一組允許 Postman 執行 Amazon Pinpoint API 操作的憑證。

**建立使用者**

1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在 IAM 主控台的導覽面板中，選擇**使用者**。選取在[建立 IAM 使用者中建立的使用者 ](#tutorials-using-postman-iam-user-create-user)(**PostmanUser**)，然後選取**安全登入**資料索引標籤。

1. 在**存取金鑰**區段中，選擇**建立存取金鑰**。

1. 在**存取金鑰最佳實務和替代方案**頁面上，選取在**外部執行的應用程式 AWS**。

   然後選擇**下一步**。

1. (選用) 您可以將描述標籤加入政策。

1. 選擇** Create access key (建立新的存取金鑰)**。

1. 在**擷取存取金鑰頁面**上，複製**存取金鑰**和**私密存取金鑰**欄位中的憑證。
**注意**  
您必須在本教學課程中，提供存取金鑰 ID 和私密存取金鑰。這是您唯一能夠檢視私密存取金鑰的時間。建議您複製並儲存在安全的位置。

1. 儲存兩個金鑰之後，選擇**完成**。

**下一步**：[設定 Postman](tutorials-using-postman-configuration.md)

# 設定 Postman 以搭配 Amazon Pinpoint 使用
<a name="tutorials-using-postman-configuration"></a>

您已經建立了能夠存取 Amazon Pinpoint API 的用戶，現在就來設定 Postman。在本節中，您將在 Postman 中建立一或多個環境。接著匯入一個集合，將 Amazon Pinpoint API 中每個操作的請求範本包含在內。

## 建立 Postman 工作區
<a name="tutorials-using-postman-configuration-create-workspace"></a>

在 Postman 中，*工作空間*是專案和環境的組織容器。本節中，您需要建立至少一個工作空間，與 Amazon Pinpoint 搭配使用。

**建立工作區**

在 Postman 中，依序選擇更多動作、**檔案**，然後選擇**新增**。

1. 在**新建**視窗中，選擇**工作空間**。

1. 輸入名稱、摘要，並將可見性設為個人。然後選擇**建立工作空間**。

## 建立 Postman 環境
<a name="tutorials-using-postman-configuration-create-environments"></a>

在 Postman 中，*環境*是儲存為鍵值組形式的一組變數。使用環境即可變更您透過 Postman 提出的請求的組態，不須變更 API 請求本身。

本節中，您需要建立至少一個環境，與 Amazon Pinpoint 搭配使用。您建立的每個環境，在單一 AWS 區域中包含一組您帳戶專用的變數。若使用本節程序建立多個環境，可從 Postman的**環境**功能表選擇不同的環境，在區域之間變更。

**建立環境**

1. 在 Postman 中，選擇更多動作功能表，選擇**檔案**，然後選擇**新增**。

1. 在 **Create New (建立新項目)** 視窗中，選擇 **Environment (環境)**。

1. 在 **MANAGE ENVIRONMENTS (管理環境)** 視窗中，對於 **Environment Name (環境名稱)**，輸入 **Amazon Pinpoint - *Region Name***。將 *Region Name (區域名稱)* 替換為下列其中一個值：
   + 美國東部 (維吉尼亞北部)
   + 美國西部 (奧勒岡)
   + 亞太地區 (孟買)
   + 亞太地區 (悉尼)
   + 歐洲 (法蘭克福)
   + 歐洲 (愛爾蘭)
**注意**  
您至少只需要為單一 建立一個環境 AWS 區域，且 AWS 區域 必須包含一個專案。如果您尚未在先前列出的其中一個 中建立專案 AWS 區域，請參閱《[Amazon Pinpoint 使用者指南》中的使用電子郵件支援建立](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-setup-create.html) *Amazon Pinpoint *專案。

1. 建立六個新變數：`endpoint`、`region`、`serviceName`、`accountId`、`accessKey` 和 `secretAccessKey`。使用下表，判斷要在每個變數的**初始值**和**目前值**欄位中輸入哪個值。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/tutorials-using-postman-configuration.html)

   建立這些變數後，**MANAGE ENVIRONMENTS (管理環境)** 視窗會類似於下圖所示的範例。  
![\[\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/Postman_Tutorial_2.1_4.png)

   完成後，請選擇**儲存**。
**重要**  
上圖中的存取金鑰是虛構的。請勿與他人共用您的 IAM 存取金鑰。  
Postman 包含的功能，可讓您分享和匯出環境。如果使用這些功能，請不要與任何無權存取這些憑證的人員分享您的存取金鑰 ID 和私密存取金鑰。  
如需詳細資訊，請參閱《[IAM 使用者指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)》中的 *IAM 最佳實務*。

1. (選用) 針對您要建立的每個其他環境，重複步驟 1 – 4。
**提示**  
在 Postman 中，您可以建立任意數量的環境。您可以透過以下方法使用環境：  
針對您必須測試 Amazon Pinpoint API 的每個區域，個別建立環境。
建立與不同 AWS 帳戶相關聯的環境。
建立使用了與其他使用者相關聯的憑證的環境。

1. 當您完成建立環境，請移至下一節。

## 在 Postman 中建立 Amazon Pinpoint 集合
<a name="tutorials-using-postman-configuration-create-pinpoint-collection"></a>

在 Postman 中，*集合*是一組 API 請求。集合中的請求通常由共同目標結合在一起。本節中，您需要在 Amazon Pinpoint API 中建立一個新集合，並包含每個操作的請求範本。

**若要建立 Amazon Pinpoint 集合**

1. 在 Postman 中，選擇更多動作功能表，選擇**檔案**，然後選擇**匯入**。

1. 在 **Import (匯入)** 視窗中，選擇 **Import From Link (從連結匯入)**，然後輸入以下 URL：[https://raw.githubusercontent.com/awsdocs/amazon-pinpoint-developer-guide/master/Amazon%20Pinpoint.postman\$1collection.json](https://raw.githubusercontent.com/awsdocs/amazon-pinpoint-developer-guide/master/Amazon%20Pinpoint.postman_collection.json)。

   選擇**匯入**。Postman 會匯入 Amazon Pinpoint 集合，該集合包含 120 個範例請求。

## 測試您的 Postman 組態
<a name="tutorials-using-postman-configuration-test-operation"></a>

匯入 Amazon Pinpoint 集合後，建議您執行快速測試，確認所有元件均已正確設定。您可以透過提交 `GetApps` 請求來測試您的組態。此請求會針對目前 AWS 區域中，您 Amazon Pinpoint 帳戶裡所有的專案，傳回一份清單。此請求不需要額外的組態，因此是測試組態的好方法。

**若要測試 Amazon Pinpoint 集合的組態**

1. 在左側導覽面板中，選取**集合**，展開 **Amazon Pinpoint** 集合，然後展開**應用程式**資料夾。

1. 在請求清單中，選擇 **GetApps**。

1. 使用**環境**選擇器選擇您在[建立 Postman 環境中建立的環境](#tutorials-using-postman-configuration-create-environments)。

1. 選擇**傳送**。如果請求成功傳送，回應窗格會顯示 `200 OK` 的狀態。您會看到類似下圖範例的回應。  
![\[\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/Postman_Tutorial_2.3_3.png)
**注意**  
如果您沒有在 中建立任何專案 AWS 區域 ，則 Amazon Pinpoint 會傳回 `{ "Item": [] }`。

   這個回應針對您在步驟 3 選擇的區域，列出帳戶中所有存在的 Amazon Pinpoint 專案。

### 疑難排解
<a name="tutorials-using-postman-configuration-test-operation-troubleshooting"></a>

當您提交請求時，可能會看到錯誤。請參閱以下清單，了解您可能會遇到的數個常見錯誤，以及您可以採取以解決問題的步驟。


| 錯誤訊息 | 問題 | Resolution | 
| --- | --- | --- | 
|  無法取得任何回應 連接到 https://%7B%7Bendpoint%7D%7D/v1/apps 時發生錯誤。  |  `{{endpoint}}` 變數沒有目前值，此值在您選擇環境時設定。  | 使用環境選擇器來選擇環境。 | 
|  包含在​要求中的安全性權杖無效。  |  Postman 找不到您存取金鑰 ID 或私密存取金鑰的目前值。  |  請選擇環境選擇器旁邊的齒輪圖示，然後選擇目前的環境。確認 `accessKey` 和 `secretAccessKey` 值已出現在 **INITIAL VALUE** 和 **CURRENT VALUE** 欄位中，且您輸入的憑證正確無誤。  | 
|  「訊息」：「使用者：arn:aws:iam::123456789012:user/PinpointPostmanUser 無權執行：mobiletargeting:GetApps on resource: arn:aws:mobiletargeting:us-west-2:123456789012:\$1」  |  與您使用者相關聯的 IAM 政策，未包含適當的許可。  |  確認您的使用者具有[建立 IAM 政策](tutorials-using-postman-iam-user.md#tutorials-using-postman-iam-user-create-policy)中所述的許可，而且您在[建立 Postman 工作區](#tutorials-using-postman-configuration-create-environments)中建立環境時提供了正確的登入資料。  | 

**下一步**：[傳送其他請求](tutorials-using-postman-sample-requests.md)

# 將請求傳送至 Amazon Pinpoint API
<a name="tutorials-using-postman-sample-requests"></a>

完成設定和測試 Postman 後，就能開始傳送其他請求到 Amazon Pinpoint API。本節告訴您，傳送請求之前必須了解哪些重要資訊，並另提供兩個請求範例，說明如何使用 Amazon Pinpoint 集合。

**重要**  
完成本節的程序後，請將請求提交到 Amazon Pinpoint API。這些請求會在您的 Amazon Pinpoint 帳戶中建立新資源、修改現有資源、傳送訊息、變更 Amazon Pinpoint 專案的組態，以及使用其他 Amazon Pinpoint 功能。執行請求時請務必小心。

## Amazon Pinpoint Postman 集合中的範例
<a name="tutorials-using-postman-sample-requests-about"></a>

您必須先在 Amazon Pinpoint Postman 集合中設定大部分的操作，才能開始使用。對於 `GET` 和 `DELETE` 操作，通常只需要修改 **Pre-request Script (預先請求指令碼)** 標籤上設定的變數。

**注意**  
當您使用建立 IAM 政策中[顯示的 IAM 政策](tutorials-using-postman-iam-user.md#tutorials-using-postman-iam-user-create-policy)時，無法執行此集合中包含的任何`DELETE`請求。

例如，`GetCampaign` 操作需要您指定 `projectId` 和 `campaignId`。在 **Pre-request Script (預先請求指令碼)** 標籤中，這兩個變數都存在，並填入範例值。刪除範例值，並將範例值替換成適合您 Amazon Pinpoint 專案和行銷活動的值。

這些變數中，最常用的是 `projectId` 變數。此變數的值應該是您請求所適用之專案的唯一識別符。若要為專案取得這些識別碼的清單，請從先前步驟傳送的 `GetApps` 請求查看回應。在該回應中，`Id` 欄位會提供專案的唯一識別碼。若要進一步了解回應中每個欄位的 `GetApps` 操作和意義，請參閱《Amazon Pinpoint API 參考》中的[應用程式](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps.html)。

**注意**  
在 Amazon Pinpoint 中，「專案」等同「應用程式」。

對於 `POST` 和 `PUT` 操作，您也必須修改請求內文，附上您要傳送到 API 的值。例如提交 `CreateApp` 請求時 (也就是 `POST` 請求)，必須為建立的專案指定名稱。您可以在 **Body (內文)** 標籤上修改請求。在這個範例中，將 `"Name"` 旁的值替換為專案的名稱。如果您想要新增標籤到專案，您可以在 `tags` 物件中指定。或者，如果您不想新增標籤，也可以刪除整個 `tags` 物件。

**注意**  
`UntagResource` 操作還需要您指定 URL 參數。您可以在 **Params (參數)** 標籤上指定這些參數。將 **VALUE (值)** 欄中的值替換為您要為指定資源刪除的標籤。

## 範例請求：使用 `CreateApp`操作建立專案
<a name="tutorials-using-postman-sample-requests-createapp"></a>

在 Amazon Pinpoint 中開始建立客群和行銷活動之前，您必須先建立一個專案。在 Amazon Pinpoint 中，*專案*包含的客群、行銷活動、組態和資料，全都具有共同目標。例如，您可以使用專案來包含與特定應用程式、特定品牌或行銷計劃相關的所有內容。將客戶資訊加入 Amazon Pinpoint 時，資訊將與專案建立關聯。

**透過傳送 CreateApp API 請求來建立專案**

1. 在**環境**功能表中，選擇您要 AWS 區域 在其中建立專案的 。  
![\[\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/Postman_Tutorial_Environments.png)

    在這個範例中，Postman 已設定為讓 **Environments (環境)** 功能表顯示以下四個選項：
   + 美國東部 (維吉尼亞北部)
   + 美國西部 (奧勒岡)
   + 歐洲 (法蘭克福)
   + 歐洲 (愛爾蘭)

1. 在**應用程式**資料夾中，選擇**CreateApp** 操作。  
![\[\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/Postman_Tutorial_3.2_2.png)

   展開的Amazon Pinpoint Postman 集合中的**應用程式**資料夾，並顯示以下請求：
   + `GetApp`
   + `GetApps`
   + `CreateApp`
   + `DeleteApp`

1. 在 **Body (內文)** 標籤的 `"Name"` 旁，將預留位置值 (`"string"`) 替換為行銷活動的名稱，例如 **"MySampleProject"**。

1. 刪除行銷活動名稱後面的逗號，然後刪除第 3 到 5 行的整個 `tags` 物件。完成後，您的請求應類似以下程式碼片段顯示的範例。

   ```
   {
       "Name": "MySampleProject"
   }
   ```

   Postman 設定為以原始 JSON 承載形式傳送請求。

1. 選擇**傳送**。如果行銷活動順利建立，回應窗格會顯示 `201 Created` 狀態。

   ```
   {
       "Name": "MySampleProject"
       "Id": "12345678901234567890123456789012",
       "Arn": "arn:aws:mobiletargeting:us-east-1:123456789012:apps/12345678901234567890123456789012",
       "tags": {}
   }
   ```

## 範例：使用 `SendMessages`操作傳送電子郵件
<a name="tutorials-using-postman-sample-requests-sendmessages"></a>

使用 Amazon Pinpoint `SendMessages` API 傳送交易訊息很常見。比起建立行銷活動，使用 `SendMessages` API 傳送訊息的其中一個優點，就是可以將訊息傳送到任何地址，例如電子郵件地址、電話號碼或裝置權杖。接收訊息的地址，不一定要在您的 Amazon Pinpoint 帳戶內。接下來就在此方法與建立行銷活動來傳送訊息這兩者之間比較。在 Amazon Pinpoint 中傳送行銷活動之前，您必須先將端點加入 Amazon Pinpoint 帳戶、建立客群、建立行銷活動，以及執行行銷活動。

本節中的範例說明如何直接傳送交易電子郵件訊息到特定的電子郵件地址。您可以修改此請求為透過其他管道傳送訊息，例如簡訊、行動推播或語音。

**若要透過提交 SendMessages 請求來傳送電子郵件訊息**

1. 確認已為專案啟用電子郵件管道，並且已設定要用來傳送和接收郵件的電子郵件地址或域。詳情請參閱 *Amazon Pinpoint 使用者指南*中的[啟用和停用電子郵件管道](pinpoint/latest/userguide/channels-email-setup.html)和[驗證電子郵件身分](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-manage-verify.html)。
**注意**  
若要完成本節的程序，您必須驗證電子郵件地址

1. 在**環境**功能表上，選擇要 AWS 區域 傳送訊息的 。

   在這個範例中，Postman 已設定為讓 **Environments (環境)** 功能表顯示以下四個選項：
   + 美國東部 (維吉尼亞北部)
   + 美國西部 (奧勒岡)
   + 歐洲 (法蘭克福)
   + 歐洲 (愛爾蘭)

1. 在 **Messages (訊息)** 資料夾中，選擇 **SendMessages** 操作。  
![\[\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/Postman_Tutorial_3.3_3.png)

1. 在 **Pre-request Script (預先請求指令碼)** 標籤中，將 `projectId` 變數取代為區域中已存在專案的 ID，或是您在本節步驟 2 中選取專案的 ID。

1. 在 **Body (內文)** 標籤上，刪除顯示在請求編輯器中的範例請求。貼上以下程式碼：

   ```
   {
       "MessageConfiguration":{
           "EmailMessage":{
               "FromAddress":"sender@example.com",
               "SimpleEmail":{
                   "Subject":{
                       "Data":"Sample Amazon Pinpoint message"
                   },
                   "HtmlPart":{
                       "Data":"<h1>Test message</h1><p>This is a sample message sent from <a href=\"https://aws.amazon.com/pinpoint\">Amazon Pinpoint</a> using the SendMessages API.</p>"
                   },
                   "TextPart":{
                       "Data":"This is a sample message sent from Amazon Pinpoint using the SendMessages API."
                   }
               }
           }
       },
       "Addresses":{
           "recipient@example.com": {
               "ChannelType": "EMAIL"
           }
       }
   }
   ```

1. 在上述程式碼中，將 *sender@example.com* 替換為您的已驗證電子郵件地址。將 *recipient@example.com* 替換成郵件的目的地電子郵件地址 (電子郵件地址必須通過驗證)。
**注意**  
如果您的帳戶仍在 Amazon Pinpoint 電子郵件沙盒中，您只能將電子郵件傳送到已在您 Amazon Pinpoint 帳戶中驗證的地址或域。如需從沙盒移除帳戶的詳細資訊，[請參閱 *Amazon Pinpoint 使用者指南*中的請求電子郵件的製作存取權](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-setup-production-access.html)。

1. 選擇**傳送**。如果訊息成功傳送，回應窗格會顯示 `200 OK` 的狀態。

   ```
   {
       "ApplicationId": "12345678901234567890123456789012",
       "RequestId": "<sampleValue>",
       "Result": {
           "recipient@example.com": {
               "DeliveryStatus": "SUCCESSFUL",
               "StatusCode": 200,
               "StatusMessage": "<sampleValue>",
               "MessageId": "<sampleValue>"
           }
       }
   }
   ```

# 在 Amazon Pinpoint 中設定簡訊註冊系統
<a name="tutorials-two-way-sms"></a>

SMS 訊息 （文字訊息） 是使用 Amazon Pinpoint 將時間敏感訊息傳送給客戶的絕佳方式。許多人隨時將手機放在附近，而 SMS 訊息比推送通知、電子郵件或電話更容易吸引人們的注意力。

擷取客戶的行動電話號碼的常見方法是使用 Web 型表單。驗證客戶的電話號碼並確認他們的訂閱後，您就可以開始傳送促銷、交易和通知簡訊給客戶。

此教學向您展示如何設定 Web 表單以擷取客戶的聯絡資訊。網頁型表單將此資訊傳送到 Amazon Pinpoint。接著 Amazon Pinpoint 會驗證電話號碼是否有效，並擷取與電話號碼相關的其他中繼資料。之後 Amazon Pinpoint 向客戶傳送訊息，要求他們確認訂閱。客戶確認訂閱後，Amazon Pinpoint 會將他們加入選擇接收訊息的清單。

以下架構圖顯示這個解決方案中的資料流。

![\[\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_Architecture.png)


## 關於雙重選擇
<a name="tutorials-two-way-sms-double-opt-in"></a>

本教學課程說明如何在 Amazon Pinpoint 中，設定使用了雙向 SMS 傳訊的雙重選擇接收系統。

在簡訊雙重選擇系統中，客戶透過在 Web 表單或您的應用程式中提交其電話號碼，提供他們的電話號碼給您。收到客戶的請求時，可以在 Amazon Pinpoint 中建立新端點。新的端點應該會選擇退出您的通訊。接著，您傳送訊息到該電話號碼。在您的訊息中，您要求收件人回覆特定的文字或片語 (如「是」或「確認」)，確認其訂閱。如果客戶以您指定的文字或片語回覆訊息，您就將端點的狀態變更為選擇加入。否則，如果客戶未回覆或以不同的文字或片語回覆，您可將該端點保留在選擇退出的狀態。

## 關於此解決方案
<a name="tutorials-two-way-sms-about"></a>

本節包含您在本教學中所建置解決方案的相關資訊。

**目標對象**  
本教學是專為開發人員和系統實作者對象而設定。您不需要熟悉 Amazon Pinpoint，也可完成本教學課程的步驟。但您應該能輕鬆管理 IAM 政策、在 Node.js 中建立 Lambda 函數，以及部署 Web 內容。

**使用的功能**  
本教學課程包含以下 Amazon Pinpoint 功能的使用範例：
+ 傳送交易簡訊
+ 使用電話號碼驗證，取得電話號碼的相關資訊。
+ 使用雙向簡訊，接收傳入簡訊
+ 建立動態客群
+ 建立行銷活動
+ 使用 與 Amazon Pinpoint API 互動 AWS Lambda

**所需時間**  
大約需要一個小時的時間來完成此教學。實作此解決方案後，您還可以採取額外的步驟來精簡解決方案，以符合您獨特的使用案例。

**區域限制**  
本教學課程需要您使用 Amazon Pinpoint 主控台租用長碼。您可以使用 Amazon Pinpoint 主控台，租用各國家/地區的專用長碼。不過只有加拿大的長碼才能用來傳送 SMS 訊息。(您可以使用位於其他國家/地區的長碼來傳送語音訊息。)

我們開發本教學中的程式碼範例時，有考慮到這個限制。例如，程式碼範例假設收件人的電話號碼一律有 10 位數，且國家代碼為 1。如果您在美國或加拿大以外的國家或區域實作此解決方案，您需要適時修改程式碼範例。

**資源用量成本**  
建立 AWS 帳戶無需付費。不過，實作此解決方案時，您可能需要支付以下費用：
+ **長碼租用費用** – 若要完成本教學課程，必須租用長碼。加拿大的長碼，月費是 1.00 USD。
+ **電話號碼驗證用量** – 本教學中的解決方案，使用 Amazon Pinpoint 的電話號碼驗證功能驗證您收到的每個號碼是否有效且格式正確，並取得電話號碼的其他資訊。每個電話號碼驗證請求的費用為 0.006 USD。
+ **訊息傳送費用** – 此教學的解決方案是傳送傳出 SMS 訊息。每透過 Amazon Pinpoint 傳送一則訊息，均須支付費用。每則訊息需支付的價格，取決於收件人的國家或區域。如果您傳送訊息到給美國 (不含美國領地) 的收件人，每則訊息需支付 0.00645 USD。傳送訊息給加拿大收件人，需支付 0.00109 – 0.02 USD 之間的費用，視收件人的電信業者和地點而定。
+ **訊息接收成本** – 這個解決方案也能接收和處理傳入的 SMS 訊息。若您的電話號碼與 Amazon Pinpoint 帳戶相關聯，您需要為每則傳入的訊息付費。支付的價格取決於收訊電話號碼所在的位置。如果您的接收號碼位於美國 (不含美國領地)，每則內送訊息需支付 0.0075 USD。如果您的號碼位於加拿大，每則內送訊息需支付 0.00155 USD。
+ **Lambda 用量** – 此解決方案使用兩個與 Amazon Pinpoint API 互動的 Lambda 函數。呼叫 Lambda 函數時，需要根據函數的請求數量、執行程式碼所需的時間，以及函數使用的記憶體量付費。本教學課程中的函數使用的記憶體極少，且通常只執行 1 – 3 秒。這個解決方案的部分或全部用量，可能屬於 Lambda 免費使用方案。如需詳細資訊，請參閱 [Lambda 定價](https://aws.amazon.com/lambda/pricing/)。
+ **API Gateway 用量** – 此解決方案中的 Web 表單，呼叫由 API Gateway 管理的 API。每 100 萬次呼叫 API Gateway 時，您需支付 3.50-3.70 USD，取決於 AWS 您使用 Amazon Pinpoint 的區域。詳情請參閱 [API 閘道定價](https://aws.amazon.com/api-gateway/pricing/)。
+ **Web 託管成本** – 這個解決方案包含一個網頁型表單，您必須將其託管在您的網站上。您需要支付的託管此內容價格，取決於您的 Web 託管供應商。

**注意**  
此清單中顯示的所有價格都以美元 (USD) 計價。

**下一步**：[先決條件](tutorials-two-way-sms-prereqs.md)

# 在 Amazon Pinpoint 中設定 SMS 的先決條件
<a name="tutorials-two-way-sms-prereqs"></a>

在您開始進行此教學之前，必須先完成下列先決條件：
+ 您必須擁有 AWS 帳戶。若要建立 AWS 帳戶，請前往 [https://console.aws.amazon.com/](https://console.aws.amazon.com/)：//www.** AWS **。
+ 您用來登入 的帳戶 AWS 管理主控台 必須能夠執行下列任務：
  + 建立新的 IAM 政策和角色
  + 建立新的 Amazon Pinpoint 專案
  + 建立新的 Lambda 函數
  + 在 API Gateway 中建立新的 API
+ 您必須擁有託管和發佈網頁的方法。雖然您可以使用 AWS 服務來託管您的網頁，但您不需要。
**提示**  
若要進一步了解如何使用 AWS 服務託管網頁，請參閱[託管靜態網頁](https://aws.amazon.com/getting-started/hands-on/host-static-website/)。

**下一步**：[設定 Amazon Pinpoint](tutorials-two-way-sms-part-1.md)

# 在 Amazon Pinpoint 中設定簡訊
<a name="tutorials-two-way-sms-part-1"></a>

您需要有 Amazon Pinpoint 專案，才能設定簡訊。請在本節執行以下動作：
+ 建立 Amazon Pinpoint 專案
+ 啟用 SMS 管道並租用電話號碼
+ 設定雙向簡訊

開始之前，請檢閱[先決條件](tutorials-two-way-sms-prereqs.md)。

## 建立 Amazon Pinpoint 專案
<a name="tutorials-two-way-sms-part-1-create-project"></a>

若要開始使用，您需要建立一個 Amazon Pinpoint 專案。在 Amazon Pinpoint 中，*專案*包含的客群、行銷活動、組態和資料，全都具有共同目標。例如，您可以使用專案來包含與特定應用程式、特定品牌或行銷計劃相關的所有內容。將客戶資訊加入 Amazon Pinpoint 時，資訊將與專案建立關聯。

建立新專案的步驟，視您之前是否在 Amazon Pinpoint 中建立了專案而不同。

### 建立一個專案 (Amazon Pinpoint 新使用者適用)
<a name="tutorials-two-way-sms-part-1-create-project-opt-1"></a>

如果您從未在目前 AWS 區域中建立專案，這些步驟會說明建立新 Amazon Pinpoint 專案的程序。

**建立專案**

1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/) 的 Amazon Pinpoint 主控台。

1. 使用區域選擇器來選擇您要使用的 AWS 區域，如下圖所示。如果不確定，請選擇位置最接近的區域。  
![\[區域下拉式清單顯示已選取美國東部 （維吉尼亞北部）。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/Region_Selector.png)

1. 在**開始使用**下，針對**名稱**，輸入行銷活動的名稱 (例如 **SMSRegistration**)，然後選擇**建立專案**。

1. 在**設定功能** 頁面上，選擇**略過此步驟**。

1. 在導覽窗格中，選擇**所有專案**。

1. 在**所有專案**頁面上，於您剛建立的專案旁邊，複製**專案 ID** 欄中顯示的值。
**提示**  
在本教學課程中，您需要在幾個不同的位置中使用此 ID。將專案 ID 放在便利位置，讓您稍後可以複製它。

### 建立一個專案 (Amazon Pinpoint 現有使用者適用)
<a name="tutorials-two-way-sms-part-1-create-project-opt-2"></a>

如果您已經在目前 AWS 區域中建立專案，這些步驟會說明建立新 Amazon Pinpoint 專案的程序。

**建立專案**

1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/) 的 Amazon Pinpoint 主控台。

1. 使用區域選擇器來選擇您要使用的 AWS 區域，如下圖所示。如果不確定，請選擇位置最接近的區域。  
![\[區域下拉式清單顯示已選取美國東部 （維吉尼亞北部）。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/Region_Selector.png)

1. 在**所有專案** 頁面上，選擇**建立專案**。

1. 在**建立專案** 視窗上，針對**專案名稱**，輸入專案的名稱 (例如 **SMSRegistration**)。選擇**建立**。

1. 在**設定功能** 頁面上，選擇**略過此步驟**。

1. 在導覽窗格中，選擇**所有專案**。

1. 在**所有專案**頁面上，於您剛建立的專案旁邊，複製**專案 ID** 欄中顯示的值。
**提示**  
在本教學課程中，您需要在幾個不同的位置中使用此 ID。將專案 ID 放在便利位置，讓您稍後可以複製它。

## 取得專用的電話號碼
<a name="tutorials-two-way-sms-part-1-set-up-channel"></a>

**注意**  
Amazon Pinpoint 已經更新了用戶指南文件。若要取得如何建立、設定和管理 SMS 和語音資源的最新資訊，請參閱新的[AWS 最終使用者簡訊簡訊使用者指南](https://docs.aws.amazon.com/sms-voice/latest/userguide/what-is-service.html)。

建立專案後，您可以開始在該專案內設定功能。本節中，您需要啟用 SMS 管道，並取得傳送 SMS 時要使用的專用長碼。

**注意**  
本節假設您在註冊品牌和行銷活動、美國免付費電話號碼或加拿大長碼後，租用美國 10DLC 電話號碼。如果您遵循本節中的程序，但選擇美國或加拿大以外的國家，則將無法使用該號碼來傳送簡訊。若要進一步了解如何在美國或加拿大以外的國家/地區租賃支援 SMS 的長碼，請參閱*AWS 《最終使用者簡訊簡訊使用者指南*》中的[支援的國家和地區 (SMS 管道）](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-sms-by-country.html)。

若要使用 Amazon Pinpoint 主控台啟用簡訊管道，請依照下列步驟執行：

**啟用簡訊管道**

1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/) 的 Amazon Pinpoint 主控台。

1. 在導覽窗格中，於**設定**下選擇 **SMS 和語音**。

1. 在**簡訊設定**旁，選擇**編輯**。

1. 在**一般設定**下，選擇**啟用此專案的簡訊管道**，然後選擇**儲存變更**。

若要使用 AWS 最終使用者簡訊 SMS 主控台請求電話號碼，請遵循下列步驟：

**請求電話號碼 (主控台)**

1. 在 https：//[https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/) 開啟 AWS 最終使用者傳訊簡訊主控台。
**注意**  
請務必在建立 Amazon Pinpoint 專案 AWS 區域 的相同 中請求電話號碼。

1. 在導覽窗格的**配置**下，選擇**電話號碼**，然後選擇**要求建立者**。

1. 在**訊息目的地國家/地區**的**選取國家/地區**頁面上，選擇美國或加拿大。選擇**下一步**。

1. 在**訊息使用案例**區段，請執行下列動作：
   + 在**數字功能**下選擇**簡訊**
**重要**  
購買電話號碼後，SMS 和語音功能將無法變更。
   + 針對**雙向傳訊**，請選擇**是**。

1. 選擇**下一步**。

1. 在**選取建立者類型**下，選擇**長碼**或 **10DLC**。

   如果您選擇 10DLC 且已註冊行銷活動，您可以從**建立與註冊活動的關聯**選擇活動。

1. 選擇**下一步**。

1. 在**檢閱和請求**中，您可以在提交請求之前驗證並編輯您的請求。選擇**請求**。

1. 根據您要求的電話號碼類型，可能會出現**需要註冊**視窗。您的電話號碼已與此註冊建立關聯，在您的註冊獲得核准之前無法傳送訊息。如需註冊需求的詳細資訊，請參閱[註冊](https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations.html)。

   1. 對於**註冊表格名稱**，請輸入易記的名稱。

   1. 選擇**開始註冊**以完成註冊電話號碼或**稍後註冊**。
**重要**  
在註冊通過核准之前，您的電話號碼無法傳送訊息。  
 無論註冊狀態為何，您仍需每月支付電話號碼的週期性租賃費用。如需註冊需求的詳細資訊，請參閱[註冊](https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations.html)。

## 啟用雙向簡訊
<a name="tutorials-two-way-sms-part-1-enable-two-way"></a>

既然您有一個專用電話號碼，就可以設定雙向簡訊。啟用雙向簡訊可讓您的客戶回應您傳送的簡訊。在此解決方案中，您使用雙向簡訊，提供您客戶一種方式，確認他們想要訂閱您的簡訊方案。

若要使用 AWS 最終使用者簡訊簡訊主控台啟用雙向簡訊，請遵循下列步驟：

**啟用雙向簡訊**

1. 在 https：//[https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/) 開啟 AWS 最終使用者傳訊簡訊主控台。

1. 在導覽窗格中，在**配置**下，選擇**電話號碼**。

1. 在**電話號碼**頁面上，選擇您的電話號碼。

1. 在**雙向 SMS**標籤上，選擇**編輯設定**按鈕。

1. 在**編輯設定**頁面上，選擇**啟用雙向訊息**。

1. 對於**目的地類型**，選擇 **Amazon SNS**。
   + **新的 Amazon SNS 主題** – AWS 使用者傳訊簡訊會在您的帳戶中建立主題。系統將自動建立主題，並授予所有必要的許可。如需 Amazon SNS 主題的詳細資訊，請參閱《Amazon SNS 開發人員指南》中的[設定 Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-configuring.html)。**
   + 針對**內送訊息目的地**，輸入主題名稱，例如 **SMSRegistrationFormTopic**。

1. 對於**雙向管道角色**，請選擇**使用 SNS 主題政策**。

1. 選擇**儲存變更**。

使用 AWS 最終使用者傳訊簡訊主控台，將關鍵字新增至您的電話號碼，客戶會傳送給您以確認其訂閱 （例如 **Yes**或 **Confirm**)。

**新增關鍵字**

1. 在 https：//[https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/) 開啟 AWS 最終使用者傳訊簡訊主控台。

1. 在導覽窗格中，於**配置**下方選擇**電話號碼**。

1. 在「**電話號碼**」頁面上，選擇要新增關鍵字的電話號碼。

1. 在「**關鍵字**」標籤上，選擇「**新增關鍵字**」按鈕。

1. 在「**自訂關鍵字**」窗格中新增下列項目：
   + **關鍵字** — 要新增的新關鍵字 (例如 **Yes** 或 **Confirm**)。
   + **回應訊息** — 要傳回給收件者的訊息。
   + **Keyword action** – 收到關鍵字時要執行的動作。選擇「**自動回應**」。

1. 選擇**新增關鍵字**。

**下一步**：[建立 IAM 政策及角色](tutorials-two-way-sms-part-2.md)

# 在 Amazon Pinpoint 中建立與 SMS 搭配使用的 IAM 政策和角色
<a name="tutorials-two-way-sms-part-2"></a>

在 Amazon Pinpoint 中實作 SMS 註冊解決方案的下一個步驟是在 AWS Identity and Access Management (IAM) 中設定政策和角色。對於這個解決方案，您需要建立一個政策，針對與 Amazon Pinpoint 相關的特定資源，提供存取權。然後您會建立角色，並將政策連接到此角色。在本教學課程稍後，您會建立 AWS Lambda 函數，此函數會使用此角色來呼叫 Amazon Pinpoint API 中的特定操作。

## 建立 IAM 政策
<a name="tutorials-two-way-sms-part-2-create-policy"></a>

本節說明如何建立 IAM 政策。使用者和角色可以使用此政策來執行下列動作：
+ 使用電話號碼驗證功能
+ 檢視、建立和更新 Amazon Pinpoint 端點
+ 將訊息傳送到 Amazon Pinpoint 端點

在本教學課程中，您將賦予 Lambda 執行這些任務的能力。不過，為了提高安全性，這個政策使用授予*最低權限*的委託人。換言之，它只授予完成此解決方案的所需許可，不會授予更多許可。此政策受到以下方面的限制：
+ 您只能使用它來呼叫特定區域中的電話號碼驗證 API。
+ 您只能用來檢視、建立或更新與特定 Amazon Pinpoint 專案相關聯的端點。
+ 您只能用來傳送訊息到與特定 Amazon Pinpoint 專案相關聯的端點。

**建立政策**

1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在導覽窗格中，選擇**政策**，然後選擇**建立政策**。

1. 在 **JSON** 標籤上，貼上下列程式碼。

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "logs:CreateLogStream",
                   "logs:PutLogEvents",
                   "logs:CreateLogGroup"
               ],
               "Resource": "arn:aws:logs:*:*:*"
           },
           {
               "Effect": "Allow",
               "Action": "mobiletargeting:SendMessages",
               "Resource": "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/*"
           },
           {
               "Effect": "Allow",
               "Action": [
                   "mobiletargeting:GetEndpoint",
                   "mobiletargeting:UpdateEndpoint",
                   "mobiletargeting:PutEvents"
               ],
               "Resource": "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/endpoints/*"
           },
           {
               "Effect": "Allow",
               "Action": "mobiletargeting:PhoneNumberValidate",
               "Resource": "arn:aws:mobiletargeting:us-east-1:111122223333:phone/number/validate"
           }
       ]
   }
   ```

------

   在上述範例中，執行下列動作：
   + 將*區域*取代為您在 `us-east-1`或 中使用 Amazon Pinpoint AWS 的區域`eu-central-1`。
**提示**  
如需 Amazon Pinpoint 可用 AWS 區域的完整清單，請參閱 中的[AWS 區域和端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#pinpoint_region)*AWS 一般參考*。
   + 將 *accountId* 取代為您 AWS 帳戶的唯一 ID。
   + 將 *projectId* 取代為您在本教學課程中[建立 Amazon Pinpoint 專案](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-create-project)所建立專案的唯一 ID。
**注意**  
`logs` 動作可讓 Lambda 將其輸出記錄在 CloudWatch Logs 中。

1. 選擇**下一步**。

1. 針對**政策名稱**，輸入政策的名稱，例如 **RegistrationFormPolicy**。選擇**建立政策**。

## 建立 IAM 角色
<a name="tutorials-two-way-sms-part-2-create-role"></a>

**建立角色**

1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在 IAM 主控台的導覽面板中，選擇**角色**，然後選擇**建立角色**。

1. 在**信任的實體類型**下，選擇**AWS 服務**，然後針對**服務或使用者案例**，從下拉式清單中選擇 **Lambda**。

1. 選擇**下一步**。

1. 在**許可政策**下，選擇或搜尋您在上一節中建立的政策，然後選擇**下一步**。

1. 在**角色詳細資訊**下，針對**角色名稱**輸入角色的名稱，例如 **SMSRegistrationForm**。選擇建**立角色**。

**下一步**：[建立 Lambda 函數](tutorials-two-way-sms-part-3.md)

# 建立 Lambda 函數以搭配 Amazon Pinpoint SMS 訊息使用
<a name="tutorials-two-way-sms-part-3"></a>

本節說明如何建立和設定兩個 Lambda 函數，以搭配 Amazon Pinpoint SMS 訊息使用。稍後，您會設定 API Gateway 和 Amazon Pinpoint，在特定事件發生時叫用這些函數。這兩個函數都會在您指定的 Amazon Pinpoint 專案中建立和更新端點。第一個函數也會使用電話號碼驗證功能。

## 建立函數來驗證客戶資訊和建立端點
<a name="tutorials-two-way-sms-part-3-create-register-function"></a>

第一個函數會從註冊表單取得輸入，該表單會從 Amazon API Gateway 接收。它使用此資訊，透過使用 Amazon Pinpoint [的電話號碼驗證](https://docs.aws.amazon.com/pinpoint/latest/developerguide/validate-phone-numbers.html)功能來取得客戶電話號碼的相關資訊。接著函數使用驗證過的資料，在您指定的 Amazon Pinpoint 專案中建立新端點。在預設情況下，函數建立的端點會選擇退出您未來的通訊，但您可以在第二個函數中變更此狀態。最後，此函數會傳送訊息給客戶，要求他們確認是否希望收到您的簡訊通訊。

**建立 Lambda 函數**

1. 在 https：//[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 開啟 AWS Lambda 主控台。

1. 選擇**建立函數**。

1. 在**建立函數**下，選擇**使用藍圖**。

1. 在搜尋欄位中，輸入 **hello**，然後按 Enter 鍵。在結果清單中，選擇 `hello-world` Node.js 函數，如下圖所示。  
![\[顯示使用所選藍圖的建立函數頁面。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_LAM_Step1.5.png)

1. 在**基本資訊**下，請執行下列動作：
   + 對於 **Name (名稱)**，輸入函數的名稱，例如 **RegistrationForm**。
   + 針對 **Role (角色)**，請選擇 **Choose an existing role (選擇現有的角色)**。
   + 針對**現有角色**，選擇您在建立 IAM 角色中建立的 **SMSRegistrationForm** 角色。 [建立 IAM 角色](tutorials-two-way-sms-part-2.md#tutorials-two-way-sms-part-2-create-role)

   完成後，請選擇 **Create function (建立函數)**。

1. 對於**程式碼來源**，請在程式碼編輯器中刪除範例函數，然後貼上下列程式碼：

   ```
   import { PinpointClient, PhoneNumberValidateCommand, UpdateEndpointCommand, SendMessagesCommand } from "@aws-sdk/client-pinpoint"; // ES Modules import
   const pinClient = new PinpointClient({region: process.env.region});  
   
   // Make sure the SMS channel is enabled for the projectId that you specify.
   // See: https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-setup.html
   var projectId = process.env.projectId;
   
   // You need a dedicated long code in order to use two-way SMS. 
   // See: https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-voice-manage.html#channels-voice-manage-request-phone-numbers
   var originationNumber = process.env.originationNumber;
   
   // This message is spread across multiple lines for improved readability.
   var message = "ExampleCorp: Reply YES to confirm your subscription. 2 msgs per "
               + "month. No purchase req'd. Msg&data rates may apply. Terms: "
               + "example.com/terms-sms";
               
   var messageType = "TRANSACTIONAL";
   
   export const handler = async (event, context) => {
     console.log('Received event:', event);
     await validateNumber(event);
   };
   
   async function validateNumber (event) {
     var destinationNumber = event.destinationNumber;
     if (destinationNumber.length == 10) {
       destinationNumber = "+1" + destinationNumber;
     }
     var params = {
       NumberValidateRequest: {
         IsoCountryCode: 'US',
         PhoneNumber: destinationNumber
       }
     };
     try{
       const PhoneNumberValidateresponse = await pinClient.send( new  PhoneNumberValidateCommand(params));
       console.log(PhoneNumberValidateresponse);
        if (PhoneNumberValidateresponse['NumberValidateResponse']['PhoneTypeCode'] == 0) {
           await createEndpoint(PhoneNumberValidateresponse, event.firstName, event.lastName, event.source);
           
         } else {
           console.log("Received a phone number that isn't capable of receiving "
                      +"SMS messages. No endpoint created.");
         }
     }catch(err){
       console.log(err);
     }
   }
   
   async function createEndpoint(data, firstName, lastName, source) {
     var destinationNumber = data['NumberValidateResponse']['CleansedPhoneNumberE164'];
     var endpointId = data['NumberValidateResponse']['CleansedPhoneNumberE164'].substring(1);
     
     var params = {
       ApplicationId: projectId,
       // The Endpoint ID is equal to the cleansed phone number minus the leading
       // plus sign. This makes it easier to easily update the endpoint later.
       EndpointId: endpointId,
       EndpointRequest: {
         ChannelType: 'SMS',
         Address: destinationNumber,
         // OptOut is set to ALL (that is, endpoint is opted out of all messages)
         // because the recipient hasn't confirmed their subscription at this
         // point. When they confirm, a different Lambda function changes this 
         // value to NONE (not opted out).
         OptOut: 'ALL',
         Location: {
           PostalCode:data['NumberValidateResponse']['ZipCode'],
           City:data['NumberValidateResponse']['City'],
           Country:data['NumberValidateResponse']['CountryCodeIso2'],
         },
         Demographic: {
           Timezone:data['NumberValidateResponse']['Timezone']
         },
         Attributes: {
           Source: [
             source
           ]
         },
         User: {
           UserAttributes: {
             FirstName: [
               firstName
             ],
             LastName: [
               lastName
             ]
           }
         }
       }
     };
     try{
       const UpdateEndpointresponse = await pinClient.send(new UpdateEndpointCommand(params));
       console.log(UpdateEndpointresponse);
       await sendConfirmation(destinationNumber);
     }catch(err){
       console.log(err);
     }  
   }
   
   async function sendConfirmation(destinationNumber) {
     var params = {
       ApplicationId: projectId,
       MessageRequest: {
         Addresses: {
           [destinationNumber]: {
             ChannelType: 'SMS'
           }
         },
         MessageConfiguration: {
           SMSMessage: {
             Body: message,
             MessageType: messageType,
             OriginationNumber: originationNumber
           }
         }
       }
     };
     try{
       const SendMessagesCommandresponse = await pinClient.send(new SendMessagesCommand(params));
       console.log("Message sent! " 
             + SendMessagesCommandresponse['MessageResponse']['Result'][destinationNumber]['StatusMessage']);
     }catch(err){
       console.log(err);
     }
   }
   ```

1. 在**環境變數**的**組態**索引標籤上，選擇**編輯**，然後選擇**新增環境變數**，然後執行下列動作：
   + 在第一個資料列，建立索引鍵為 **originationNumber** 的變數。接著，將其值設定為您在[步驟 1.2](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-set-up-channel) 中所收到專屬長碼的電話號碼。
**注意**  
請務必加上加號 (\$1) 和電話號碼的國家/地區代碼。不要包含任何其他特殊字元，例如連字號 (-)、句號 (.) 或括號。
   + 在第二個資料列，建立索引鍵為 **projectId** 的變數。接著，將其值設定為您在[步驟 1.1](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-create-project) 中所建立專案的唯一 ID。
   + 在第三個資料列，建立索引鍵為 **region** 的變數。接著將該值設為您使用 Amazon Pinpoint 的區域，例如 **us-east-1** 或 **us-west-2**。

   完成後，**Environment Variables (環境變數)** 區段應該類似於下圖所示的範例。  
![\[originationNumber、projectId 和區域的環境變數。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_LAM_Step1.7.png)

1. 在頁面頂端選擇 **Save (儲存)**。

### 測試函數
<a name="tutorials-two-way-sms-part-3-create-register-function-test"></a>

建立函數後，您應該對其進行測試，以確保您的正確設定。此外請確認您建立的 IAM 角色具有適當的許可。

**若要測試函數**

1. 選擇**測試**標籤。

1. 選擇**建立新事件**，執行下列動作：
   + 針對 **Event name (事件名稱)**，輸入測試事件的名稱，例如 **MyPhoneNumber**。
   + 在程式碼編輯器中清除範例程式碼。貼上以下程式碼：

     ```
     {
       "destinationNumber": "+12065550142",
       "firstName": "Carlos",
       "lastName": "Salazar",
       "source": "Registration form test"
     }
     ```
   + 在上述程式碼範例中，將 `destinationNumber`, `firstName` 和 `lastName` 屬性替換為您想用於測試的值，例如您的個人聯絡詳細資訊。測試此函數時，函數會傳送簡訊到您在 `destinationNumber` 屬性中指定的電話號碼。請確定您指定的電話號碼可以接收簡訊。
   + 選擇**建立**。

1. 選擇**測試**。

1. 在 **Execution result: succeeded (執行結果：成功)** 下方，選擇 **Details (詳細資訊)**。在 **Log output (記錄輸出)** 區段，檢閱函數的輸出。確定函數執行沒有發生錯誤。

   檢查與您指定之 `destinationNumber` 關聯的裝置，確定它有收到測試訊息。

1. 開啟位於 [https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/) 的 Amazon Pinpoint 主控台。

1. **在所有專案**頁面上，選擇您在[建立 Amazon Pinpoint 專案中建立的專案](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-create-project)。

1. 在導覽窗格中，選擇 **Segments (客群)**。在 **Segments (客群)** 頁面，選擇 **Create a segment (建立客群)**。

1. 在 **Segment group 1 (客群群組 1)** 的 **Add filters to your segment (新增篩選條件來精簡客群)** 中，選擇 **Filter by user (依使用者篩選)**。

1. 對於 **Choose a user attribute (選擇使用者屬性)**，選擇 **FirstName**。然後，對於 **Choose values (選擇值)**，選擇您在測試事件中指定的名字。

   **Segment estimate (客群估計)** 區段應該會顯示有零個符合資格的端點、一個總端點，如下圖所示。這個結果是正常的。當函數建立新的端點時，端點會選擇退出。Amazon Pinpoint 中的客群會自動排除已選擇不接收的端點。  
![\[區段群組顯示零端點。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_LAM_Step8.9.png)

## 建立函數以將客戶選擇加入您的通訊
<a name="tutorials-two-way-sms-part-3-create-optin-function"></a>

只有當客戶回覆由第一個函數傳送的訊息時，才會執行第二個函數。如果客戶的回覆包含您在[啟用雙向 SMS](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-set-up-channel) 中指定的關鍵字，則函數會更新其端點記錄，以選擇加入未來的通訊。Amazon Pinpoint 也會自動回應您在[啟用雙向簡訊](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-set-up-channel)中指定的訊息。

如果客戶不回應或回應指定關鍵字以外的其他內容，則不會發生任何事。客戶的端點仍在 Amazon Pinpoint 中，但不能被客群鎖定。

**建立 Lambda 函數**

1. 在 https：//[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 開啟 AWS Lambda 主控台。

1. 選擇**建立函數**。

1. 在 **Create function (建立函數)** 下方，選擇 **Blueprints (藍圖)**。

1. 在搜尋欄位中，輸入 **hello**，然後按 Enter 鍵。在結果清單中，選擇 `hello-world` Node.js 函數，如下圖所示。選擇**設定**。

1. 在**基本資訊**下，請執行下列動作：
   + 對於 **Name (名稱)**，輸入函數的名稱，例如 **RegistrationForm\$1OptIn**。
   + 針對 **Role (角色)**，請選擇 **Choose an existing role (選擇現有的角色)**。
   + 針對**現有角色**，選擇您在建立 IAM 角色中建立的 SMSRegistrationForm 角色。 [建立 IAM 角色](tutorials-two-way-sms-part-2.md#tutorials-two-way-sms-part-2-create-role)

   完成後，請選擇 **Create function (建立函數)**。

1. 在程式碼編輯器中刪除範例函數，然後貼上以下程式碼：

   ```
   import { PinpointClient, UpdateEndpointCommand } from "@aws-sdk/client-pinpoint"; // ES Modules import
   
   // Create a new Pinpoint client instance with the region specified in the environment variables
   const pinClient = new PinpointClient({ region: process.env.region });
   
   // Get the Pinpoint project ID and the confirm keyword from environment variables
   const projectId = process.env.projectId;
   const confirmKeyword = process.env.confirmKeyword.toLowerCase();
   
   // This is the main handler function that is invoked when the Lambda function is triggered
   export const handler = async (event, context) => {
       console.log('Received event:', event);
   
       try {
           // Extract the timestamp, message, and origination number from the SNS event
           const timestamp = event.Records[0].Sns.Timestamp;
           const message = JSON.parse(event.Records[0].Sns.Message);
           const originationNumber = message.originationNumber;
           const response = message.messageBody.toLowerCase();
   
           // Check if the response message contains the confirm keyword
           if (response.includes(confirmKeyword)) {
               // If the confirm keyword is found, update the endpoint's opt-in status
               await updateEndpointOptIn(originationNumber, timestamp);
           }
       }catch (error) {
           console.error('An error occurred:', error);
           throw error; // Rethrow the error to handle it upstream
       }
   };
   
   // This function updates the opt-in status of a Pinpoint endpoint
   async function updateEndpointOptIn(originationNumber, timestamp) {
       // Extract the endpoint ID from the origination number
       const endpointId = originationNumber.substring(1);
   
        // Prepare the parameters for the UpdateEndpointCommand
       const params = {
           ApplicationId: projectId,
           EndpointId: endpointId,
           EndpointRequest: {
               Address: originationNumber,
               ChannelType: 'SMS',
               OptOut: 'NONE',
               Attributes: {
                   OptInTimestamp: [timestamp]
               },
           }
       };
   
       try {
           // Send the UpdateEndpointCommand to update the endpoint's opt-in status
           const updateEndpointResponse = await pinClient.send(new UpdateEndpointCommand(params));
           console.log(updateEndpointResponse);
           console.log(`Successfully changed the opt status of endpoint ID ${endpointId}`);
       } catch (error) {
           console.error('An error occurred while updating endpoint:', error);
           throw error; // Rethrow the error to handle it upstream
       }
   }
   ```

1. 在 **Environment variables (環境變數)** 下，執行下列動作：
   + 在第一個資料列，建立索引鍵為 **projectId** 的變數。接著，將值設定為您在[建立 Amazon Pinpoint ](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-create-project)專案中建立之專案的唯一 ID。
   + 在第二個資料列，建立索引鍵為 **region** 的變數。接著將該值設為您使用 Amazon Pinpoint 的區域，例如 **us-east-1** 或 **us-west-2**。
   + 在第三個資料列，建立索引鍵為 **confirmKeyword** 的變數。接著，將值設定為您在[啟用雙向簡訊](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-set-up-channel)中建立的確認關鍵字。
**注意**  
關鍵字不區分大小寫。此函數會將傳入訊息轉換為小寫字母。

   完成後，**Environment Variables (環境變數)** 區段應該類似於下圖所示的範例。  
![\[projectId、region 和 confirmKeyword 的環境變數。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_LAM_Step2.7.png)

1. 在頁面頂端選擇 **Save (儲存)**。

### 測試函數
<a name="tutorials-two-way-sms-part-3-create-optin-function-test"></a>

建立函數後，您應該對其進行測試，以確保您的正確設定。此外請確認您建立的 IAM 角色具有適當的許可。

**若要測試函數**

1. 選擇**測試**。

1. 在 **Configure test event (設定測試事件)** 視窗中，執行以下操作：

   1. 選擇 **建立新測試事件**。

   1. 針對 **Event name (事件名稱)**，輸入測試事件的名稱，例如 **MyResponse**。

   1. 在程式碼編輯器中清除範例程式碼。貼上以下程式碼：

      ```
      {
        "Records":[
          {
            "Sns":{
              "Message":"{\"originationNumber\":\"+12065550142\",\"messageBody\":\"Yes\"}",
              "Timestamp":"2019-02-20T17:47:44.147Z"
            }
          }
        ]
      }
      ```

      在上述程式碼範例中，將 `originationNumber` 屬性的值替換成您在測試舊 Lambda 函數時使用的電話號碼。將 的值取代`messageBody`為您在[啟用雙向 SMS 中指定的雙向 SMS ](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-enable-two-way)關鍵字。或者，您也可以將 `Timestamp` 的值替換為目前的日期和時間。

   1. 選擇**建立**。

1. 再次選擇 **Test (測試)**。

1. 在 **Execution result: succeeded (執行結果：成功)** 下方，選擇 **Details (詳細資訊)**。在 **Log output (記錄輸出)** 區段，檢閱函數的輸出。確定函數執行沒有發生錯誤。

1. 開啟位於 [https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/) 的 Amazon Pinpoint 主控台。

1. **在所有專案**頁面上，選擇您在[建立 Amazon Pinpoint 專案中建立的專案](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-create-project)。

1. 在導覽窗格中，選擇 **Segments (客群)**。在 **Segments (客群)** 頁面，選擇 **Create a segment (建立客群)**。

1. 在 **Segment group 1 (客群群組 1)** 的 **Add filters to your segment (新增篩選條件來精簡客群)** 中，選擇 **Filter by user (依使用者篩選)**。

1. 對於 **Choose a user attribute (選擇使用者屬性)**，選擇 **FirstName**。然後，對於 **Choose values (選擇值)**，選擇您在測試事件中指定的名字。

   **Segment estimate (客群估計)** 區段應該會顯示有一個符合資格的端點，以及一個總端點。

**下一步**：[設定 Amazon API Gateway](tutorials-two-way-sms-part-4.md)

# 在 Amazon Pinpoint 中設定 SMS 訊息的 Amazon API Gateway Amazon Pinpoint
<a name="tutorials-two-way-sms-part-4"></a>

在本節中，您會使用 Amazon API Gateway 作為 Amazon Pinpoint SMS 註冊的一部分來建立新的 API。 Amazon Pinpoint 您在此解決方案中部署的註冊表單，呼叫此 API。API Gateway 接著會將註冊表單上擷取的資訊傳遞至您在建立 Lambda 函數中[建立的 Lambda 函數](tutorials-two-way-sms-part-3.md)。

## 建立 API
<a name="tutorials-two-way-sms-part-4-create-api"></a>

首先，您必須在 API Gateway 中建立新的 API。下列程序顯示如何建立新的 REST API。

**建立新的 API**

1. 在以下網址開啟 API Gateway 主控台：[https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/)。

1. 選擇**建立 API**。選擇如下：
   + 在 **Choose the protocol (選擇通訊協定)** 下，選擇 **REST**。
   + 在 **Create new API** (建立新 API) 下，選擇 **New API** (新增 API)。
   + 在 **Settings (設定)** 下方的 **Name (名稱)** 中，輸入名稱，例如 **RegistrationForm**。對於 **Description (描述)**，選擇性地輸入可描述 API 用途的一些文字。對於 **Endpoint Type** (端點類型)，選擇 **Regional** (區域)。然後選擇 **Create API (建立 API)**。

   下圖顯示這些設定的範例。  
![\[通訊協定設定為 REST、建立新的 API 設定為新 API、API 名稱設定為 RegistrationForm，以及端點類型設定為區域。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_APIGW_Step2.png)

## 建立資源
<a name="tutorials-two-way-sms-part-4-create-resource"></a>

現在您已建立 API，您可以開始新增資源。接著將 POST 方法加入資源，並告訴 API Gateway 將這個方法收到的資料傳遞到 Lambda 函數。

1. 在 **Actions (動作)** 功能表中，選擇 **Create Resource (建立資源)**。在 **New Child Resource (新的子資源)** 窗格中，對於 **Resource Name (資源名稱)**，輸入 **register**，如下圖所示。選擇 **建立資源** 。  
![\[將資源名稱設定為註冊的新子資源窗格。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_APIGW_Step3.png)

1. 在 **Actions (動作)** 功能表中，選擇 **Create method (建立方法)**。從功能表中，選擇 **POST**，如下圖所示。然後選擇**核取記號**按鈕。  
![\[選取核取記號的建立方法窗格。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_APIGW_Step4.png)

1. 在 **/register - POST - Setup (/註冊 - POST - 設定)** 窗格中，選取下列項目：
   + 針對 **整合類型** ，選擇 **Lambda 函數** 。
   + 選擇**使用 Lambda 代理整合**。
   + 在 **Lambda 區域**中，選擇您建立 Lambda 函數的區域。
   + 針對 **Lambda 函數**，選擇您在建立 Lambda 函數中建立的 RegisterEndpoint 函數。 [建立 Lambda 函數以搭配 Amazon Pinpoint SMS 訊息使用](tutorials-two-way-sms-part-3.md)

   下圖顯示這些設定的範例。  
![\[選取 Lambda 函數的 /register - POST - 設定窗格。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_APIGW_Step5.png)

   選擇**儲存**。在出現的視窗中，選擇**確定**，以授予 API Gateway 執行 Lambda 函數的許可。

## 部署 API
<a name="tutorials-two-way-sms-part-4-deploy-api"></a>

API 現在已準備好可供使用。此時，您必須部署它以便建立可公開存取的端點。

1. 在 **Action (動作)** 功能表中，選擇 **Deploy API (部署 API)**。在 **Deploy API (部署 API)** 視窗上，選取下列項目：
   + 針對 **Deployment stage (部署階段)**，選擇 **[New Stage] ([新增階段])**。
   + 針對 **Stage name (階段名稱)**，輸入 **v1**。
   + 選擇 **Deploy (部署)**。

   下圖顯示這些選取項目的範例。  
![\[階段名稱設為 v1 的部署 API 視窗\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_APIGW_Step6.png)

1. 在 **v1 Stage Editor (v1 階段編輯器)** 窗格中，選擇 **/register (/註冊)** 資源，然後選擇 **POST** 方法。複製 **Invoke URL (呼叫 URL)** 旁顯示的地址，如下圖所示。  
![\[v1 階段編輯器窗格顯示要複製的調用 URL\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_APIGW_Step7.png)

1. 在導覽窗格中，選擇 **Resources** (資源)。在資源清單中，選擇 **/register (/註冊)** 資源。最後，在 **Actions (動作)** 功能表中，選擇 **Enable CORS (啟用 CORS)**，如下圖所示。  
![\[動作的下拉式選單，顯示已選取啟用 CORS\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_APIGW_Step8.png)

1. 在 **Enable CORS (啟用 CORS)** 窗格中，選擇 **Enable CORS and replace existing CORS headers (啟用 CORS 並取代現有的 CORS 標頭)**。

**下一步**：[建立和部署 Web 表單](tutorials-two-way-sms-part-5.md)

# 建立和部署 Web 表單，以使用 Amazon Pinpoint 的簡訊
<a name="tutorials-two-way-sms-part-5"></a>

使用 AWS 服務透過 Amazon Pinpoint 傳送簡訊的所有元件現在都已就緒。最後一個步驟是建立和部署 Web 表單，用來擷取客戶的資料。

## 建立 JavaScript 表單處理常式
<a name="tutorials-two-way-sms-part-5-create-form-handler"></a>

在本節中，您將建立一個 JavaScript 函數，用來剖析您在下一節中建立之 Web 表單的內容。剖析內容後，此函數會將資料傳送至您在[設定 Amazon API Gateway 中建立的 API](tutorials-two-way-sms-part-4.md)。

**建立表單處理常式**

1. 在文字編輯器中，建立新檔案。

1. 在編輯器中，貼上以下程式碼。

   ```
   $(document).ready(function() {
   
     // Handle form submission.
     $("#submit").click(function(e) {
   
       var firstName = $("#firstName").val(),
           lastName = $("#lastName").val(),
           source = window.location.pathname,
           optTimestamp = undefined,
           utcSeconds = Date.now() / 1000,
           timestamp = new Date(0),
           phone = $("#areaCode").val()
                 + $("#phone1").val()
                 + $("#phone2").val();
   
       e.preventDefault();
   
       if (firstName == "") {
         $('#form-response').html('<div class="mt-3 alert alert-info" role="alert">Please enter your first name.</div>');
       } else if (lastName == "") {
         $('#form-response').html('<div class="mt-3 alert alert-info" role="alert">Please enter your last name.</div>');
       } else if (phone.match(/[^0-9]/gi)) {
         $('#form-response').html('<div class="mt-3 alert alert-info" role="alert">Your phone number contains invalid characters. Please check the phone number that you supplied.</div>');
       } else if (phone.length < 10) {
         $('#form-response').html('<div class="mt-3 alert alert-info" role="alert">Please enter your phone number.</div>');
       } else if (phone.length > 10) {
         $('#form-response').html('<div class="mt-3 alert alert-info" role="alert">Your phone number contains too many digits. Please check the phone number that you supplied.</div>');
       } else {
         $('#submit').prop('disabled', true);
         $('#submit').html('<span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>  Saving your preferences</button>');
   
         timestamp.setUTCSeconds(utcSeconds);
   
         var data = JSON.stringify({
           'destinationNumber': phone,
           'firstName': firstName,
           'lastName': lastName,
           'source': source,
           'optTimestamp': timestamp.toString()
         });
   
         $.ajax({
           type: 'POST',
           url: 'https://example.execute-api.us-east-1.amazonaws.com/v1/register',
           contentType: 'application/json',
           data: data,
           success: function(res) {
             $('#form-response').html('<div class="mt-3 alert alert-success" role="alert"><p>Congratulations! You&apos;ve successfully registered for SMS Alerts from ExampleCorp.</p><p>We just sent you a message. Follow the instructions in the message to confirm your subscription. We won&apos;t send any additional messages until we receive your confirmation.</p><p>If you decide you don&apos;t want to receive any additional messages from us, just reply to one of our messages with the keyword STOP.</p></div>');
             $('#submit').prop('hidden', true);
             $('#unsubAll').prop('hidden', true);
             $('#submit').text('Preferences saved!');
           },
           error: function(jqxhr, status, exception) {
             $('#form-response').html('<div class="mt-3 alert alert-danger" role="alert">An error occurred. Please try again later.</div>');
             $('#submit').text('Save preferences');
             $('#submit').prop('disabled', false);
           }
         });
       }
     });
   });
   ```

1. 在上述範例中，將 *https://example.execute-api.us-east-1.amazonaws.com/v1/register* 取代為您在[部署 API](tutorials-two-way-sms-part-4.md#tutorials-two-way-sms-part-4-deploy-api) 中取得的調用 URL。

1. 儲存檔案。

## 建立表單檔案
<a name="tutorials-two-way-sms-part-5-create-form"></a>

在本節中，您將建立 HTML 檔案，其中包含客戶用來註冊您的簡訊方案的表單。這個檔案使用您在上一節建立的 JavaScript 表單處理常式，將表單資料傳輸到 Lambda 函數。

**重要**  
使用者提交此表單時，會觸發 Lambda 函數，呼叫多個 Amazon Pinpoint API 操作。惡意使用者可能在您的表單發動攻擊，發出大量請求。如果您計劃將此解決方案用於生產使用案例，您應該使用 [Google reCAPTCHA](https://www.google.com/recaptcha/about/) 之類的系統來保護其安全。

**建立表單**

1. 在文字編輯器中，建立新檔案。

1. 在編輯器中，貼上以下程式碼。

   ```
   <!doctype html>
   <html lang="en">
   
   <head>
     <!-- Meta tags required by Bootstrap -->
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
   
     <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
     <script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous"></script>
     <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
     <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
   
     <script type="text/javascript" src="SMSFormHandler.js"></script>
     <title>SMS Registration Form</title>
   </head>
   
   <body>
     <div class="container">
       <div class="row justify-content-center mt-3">
         <div class="col-md-6">
           <h1>Register for SMS Alerts</h1>
           <p>Enter your phone number below to sign up for PromotionName messages from ExampleCorp.</p>
           <p>We don't share your contact information with anyone else. For more information, see our <a href="http://example.com/privacy">Privacy Policy</a>.</p>
           <p>ExampleCorp alerts are only available to recipients in the United States.</p>
         </div>
       </div>
       <div class="row justify-content-center">
         <div class="col-md-6">
           <form>
             <div class="form-group">
               <label for="firstName" class="font-weight-bold">First name</label>
               <input type="text" class="form-control" id="firstName" placeholder="Your first name" required>
             </div>
             <div class="form-group">
               <label for="lastName" class="font-weight-bold">Last name</label>
               <input type="text" class="form-control" id="lastName" placeholder="Your last name" required>
             </div>
             <label for="areaCode" class="font-weight-bold">Phone number</label>
             <div class="input-group">
               <span class="h3">(&nbsp;</span>
               <input type="tel" class="form-control" id="areaCode" placeholder="Area code" required>
               <span class="h3">&nbsp;)&nbsp;</span>
               <input type="tel" class="form-control" id="phone1" placeholder="555" required>
               <span class="h3">&nbsp;-&nbsp;</span>
               <input type="tel" class="form-control" id="phone2" placeholder="0199" required>
             </div>
             <div id="form-response"></div>
             <button id="submit" type="submit" class="btn btn-primary btn-block mt-3">Submit</button>
           </form>
         </div>
       </div>
       <div class="row mt-3">
         <div class="col-md-12 text-center">
           <small class="text-muted">Copyright © 2019, ExampleCorp or its affiliates.</small>
         </div>
       </div>
     </div>
   </body>
   
   </html>
   ```

1. 在上述範例中，將 *SMSFormHandler.js* 替換為您在上一節所建立表單處理常式 JavaScript 檔案的完整路徑。

1. 儲存檔案。

## 上傳表單檔案
<a name="tutorials-two-way-sms-part-5-upload-form"></a>

現在您已建立 HTML 表單和 JavaScript 表單處理常式，最後一個步驟是將這些檔案發佈至網際網路。本節假設您已具備現有的 Web 託管供應商。若您不是現有的託管供應商，您可以使用 Amazon Route 53、Amazon Simple Storage Service (Amazon S3) 和 Amazon CloudFront 啟動網站。如需詳細資訊，請參閱[託管靜態網站](https://aws.amazon.com/getting-started/hands-on/host-static-website/)。

如果您使用其他 Web 託管供應商，請參閱供應商的文件以取得發佈網頁的相關資訊。

## 測試表單
<a name="tutorials-two-way-sms-part-5-test-form"></a>

提交表單後，您應該提交一些測試事件，以確保它能如預期運作。

**測試註冊表單**

1. 在 Web 瀏覽器中，移至您上傳註冊表單的位置。如果您使用來自[建立 JavaScript 表單處理常式的](#tutorials-two-way-sms-part-5-create-form)程式碼範例，您會在下圖中看到類似範例的表單。  
![\[步驟 5.1 中建立的客戶申請表。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_Form_Step5.3.1.png)

1. 在 **First name (名字)**、**Last name (姓氏)** 和 **Phone number (電話號碼)** 欄位輸入您的聯絡資訊。
**注意**  
提交表單後，Amazon Pinpoint 會嘗試傳送訊息到您指定的電話號碼。由於此項功能，您應該使用真實的電話號碼，才能從頭到尾測試解決方案。  
如果您在[建立 Lambda 函數中測試 Lambda 函數](tutorials-two-way-sms-part-3.md)，您的 Amazon Pinpoint 專案至少已包含一個端點。測試此表單時，您應該在表單上提交不同的電話號碼或使用 [DeleteEndpoint](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-endpoints-endpoint-id.html#DeleteEndpoint) API 操作刪除現有的端點。

1. 檢查與您指定之電話號碼關聯的裝置，確保有收到訊息。

1. 開啟位於 [https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/) 的 Amazon Pinpoint 主控台。

1. **在所有專案**頁面上，選擇您在[建立 Amazon Pinpoint 專案中建立的專案](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-create-project)。

1. 在導覽窗格中，選擇 **Segments (客群)**。在 **Segments (客群)** 頁面，選擇 **Create a segment (建立客群)**。

1. 在 **Segment group 1 (客群群組 1)** 的 **Add filters to your segment (新增篩選條件來精簡客群)** 中，選擇 **Filter by user (依使用者篩選)**。

1. 對於 **Choose a user attribute (選擇使用者屬性)**，選擇 **FirstName**。然後，對於 **Choose values (選擇值)**，選擇您在提交表單時指定的名字。

   **Segment estimate (客群估計)** 區段應該會顯示有零個符合資格的端點以及一個端點 (位於總端點下)，如下圖所示。這個結果是正常的。Lambda 函數建立一個新端點時，預設是不選擇該端點。  
![\[端點選擇為零的區段。\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/userguide/images/SMS_Reg_Tutorial_LAM_Step8.9.png)

1. 在接收訊息的裝置上，使用您在[啟用雙向簡訊中指定的雙向簡訊關鍵字回覆訊息](tutorials-two-way-sms-part-1.md#tutorials-two-way-sms-part-1-enable-two-way)。Amazon Pinpoint 會立即傳送回應訊息。

1. 在 Amazon Pinpoint 主控台中，重複步驟 4 到 8。目前，當您建立客群時，您會看到一個符合資格的端點，以及一個總端點。這個結果是正常的，因為端點現在已選擇加入。

# 後續步驟
<a name="tutorials-two-way-sms-next-steps"></a>

完成本教學課程後，表示您已執行下列操作：
+ 建立一個 Amazon Pinpoint 專案、設定 SMS 管道，並取得專用長碼。
+ 建立一個使用最低權限主體授予存取權的 IAM 政策，並將該政策與角色建立關聯。
+ 在 Amazon Pinpoint API 中，建立了兩個使用 PhoneNumberValidate、UpdateEndpoint 和 SendMessages 操作的 Lambda 函數。
+ 使用 API Gateway 建立 REST API。
+ 建立和部署 Web 型表單，來收集客戶的聯絡資訊。
+ 對解決方案執行測試，以確保其正常運作。

本節討論幾種方式，您可以藉此使用您使用此解決方案收集的客戶資訊。它還包含一些建議的方式，您可以藉此自訂此解決方案，以符合獨特的使用案例。

## 建立客戶客群
<a name="tutorials-two-way-sms-next-steps-create-segments"></a>

您透過此表單收集的所有客戶詳細資訊都會儲存為端點。此解決方案會建立包含數個屬性的端點，您可以將這些屬性用於建立客群。

例如，此解決方案會擷取稱為 `Source` 的端點屬性。此屬性包含表單託管位置的完整路徑。建立客群時，您可以依端點篩選客群，然後選擇 `Source` 屬性來進一步精簡篩選條件。

根據 `Source` 屬性建立客群提供數個有用的方式。首先，它可讓您快速建立客戶的客群，而這些客戶已註冊，可從您那裡接收簡訊。此外，Amazon Pinpoint 中的分割工具會自動排除未選擇接收訊息的端點。

如果您決定在數個不同位置託管註冊表單，則 `Source` 屬性也很有用。例如，您的行銷資料可能參考某個位置託管的表單，而在瀏覽您網站時客戶遇到此表單的客戶可能看到別的地方託管的版本。當您執行此操作時，在看到您的行銷資料之後完成表單之客戶的來源屬性不同於在您網站上發現它之後完成表單的客戶。您可以使用此差異來建立不同的客群，然後將量身訂做的通訊傳送至其中每一個對象。

## 傳送個人化的行銷活動訊息
<a name="tutorials-two-way-sms-next-steps-send-campaigns"></a>

建立客群後，您可以開始將行銷活動傳送給這些客群。建立行銷活動訊息時，您可以將它們個人化，方法為指定想要將哪些端點屬性包含在訊息中。例如，此解決方案中使用的 Web 表單需要客戶輸入他們的名字和姓氏。這些值會儲存在與端點相關聯的使用者記錄中。

例如，如果您使用 `GetEndpoint` API 操作，來擷取使用此解決方案所建立之端點的相關資訊，您會看到類似以下範例的區段：

```
  ...
  "User": {
    "UserAttributes": {
      "FirstName": [
        "Carlos"
      ],
      "LastName": [
        "Salazar"
      ]
    }
  }
  ...
```

如果您想要在行銷活動訊息中包含這些屬性的值，可以使用點表示法來參考屬性。然後，以雙大括號括住整個參考。例如，若要在行銷活動訊息中包含每個收件人的名字，請在訊息中包含下列字串：`{{User.UserAttributes.FirstName}}`。Amazon Pinpoint 傳送訊息時，會將字串替換成 `FirstName` 屬性的值。

## 使用表單來收集其他資訊
<a name="tutorials-two-way-sms-next-steps-collect-additional"></a>

您可以修改此解決方案，以收集註冊表單的其他資訊。例如，您可以要求客戶提供其地址，然後使用該地址資料填入 `Endpoint` 資源中的 `Location.City`、`Location.Country`、`Location.Region` 和 `Location.PostalCode` 欄位。收集註冊表單上的地址資訊可能導致端點包含更準確的資訊。若要進行此變更，您需要將適當的欄位新增至 Web 表單。您也須修改表單的 JavaScript 程式碼，以傳遞新值。最後您必須修改建立端點的 Lambda 函數，才能處理新的傳入資訊。

您也可以修改表單，讓其可以收集其他管道中的聯絡資訊。例如，除了客戶的電話號碼以外，您還可以使用表單來收集客戶的電子郵件地址。若要進行此變更，您需要修改 Web 表單的 HTML 和 JavaScript。您也必須修改建立端點的 Lambda 函數，使其建立兩個單獨的端點 (一個用於電子郵件端點，一個用於 SMS 端點)。您也應該修改 Lambda 函數，為 `User.UserId` 屬性產生唯一值，然後將該值與兩個端點建立關聯。

## 記錄其他屬性以供稽核之用
<a name="tutorials-two-way-sms-next-steps-auditing"></a>

這個解決方案會在建立和更新端點時記錄兩個珍貴的屬性。首先，第一個 Lambda 函數開始建立端點時，會在 `Attributes.Source` 屬性中記錄表單的 URL。如果客戶回應訊息，第二個 Lambda 函數將建立 `Attributes.OptInTimestamp` 屬性。此屬性包含客戶同意接收來自您的訊息的確切日期和時間。

如果行動電信業者或監管機構曾經要求您提供客戶同意的證據，這兩個欄位很有用。您可以隨時使用 [GetEndpoint](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-endpoints-endpoint-id.html#GetEndpoint) API 操作來擷取此資訊。

您也可以修改 Lambda 函數，以記錄可能對審核有用的其他資料，例如提交註冊請求的 IP 地址。