**支援終止通知：**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 最終使用者傳訊支援。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Amazon Pinpoint 中使用推薦者模型搭配 AWS Lambda
您可以在 Amazon Pinpoint 中，從推薦者模型擷取個人化建議，並加入您要透過行銷活動和旅程傳送的訊息中。*推薦人模型*是一種機器學習 (ML) 模型，可在資料中找出模式，並根據它找到的模式產生預測和建議。它會預測特定使用者偏好的一組特定產品或項目，並以一組建議的形式將該資訊提供給使用者。
透過 Amazon Pinpoint 使用推薦者模型，就能根據每個收件人的屬性和行為，將個人化建議傳送給訊息收件人。透過 AWS Lambda，您也可以自訂和增強這些建議。例如，您可以動態將建議從單一文字值 (例如產品名稱或 ID) 轉換為更複雜的內容 (例如產品名稱、描述和影像)。Amazon Pinpoint 傳送訊息時，您也可以即時執行此操作。
此功能適用於下列 AWS 區域：美國東部 （維吉尼亞北部）、美國西部 （奧勒岡）、亞太區域 （孟買）、亞太區域 （雪梨） 和歐洲 （愛爾蘭）。
# 將推薦者模型建議新增至 Amazon Pinpoint 中的訊息
若要將推薦者模型搭配 Amazon Pinpoint 使用，您可以先從建立 Amazon Personalize 解決方案開始，然後將該解決方案部署為 Amazon Personalize 行銷活動。然後您可以在 Amazon Pinpoint 中建立推薦者模型的組態。您可以在組態中指定設定，決定從 Amazon Personalize 行銷活動，擷取和處理建議資料的方式。這包括是否叫用 AWS Lambda 函數來執行所擷取資料的額外處理。
Amazon Personalize 是一項 AWS 服務，旨在協助您建立 ML 模型，為使用應用程式的客戶提供即時、個人化的建議。Amazon Personalize 會引導您完成建立和訓練 ML 模型的程序，然後將模型準備和部署為 Amazon Personalize 行銷活動。然後，您可以從行銷活動中擷取即時、個人化建議。若要進一步了解 Amazon Personalize，請參閱 [Amazon Personalize 開發人員指南](https://docs.aws.amazon.com/personalize/latest/dg/what-is-personalize.html)。
AWS Lambda 是一種運算服務，您可以用來執行程式碼，而無需佈建或管理伺服器。您可以封裝程式碼並將其上傳到 AWS Lambda 做為 *Lambda 函數*。 AWS Lambda 然後， 會在叫用函數時執行函數。您可以手動調用函數，也可以根據事件，或根據應用程式或服務 (包括 Amazon Pinpoint) 提出的請求，自動調用函數。如需建立並調用 Lambda 函數的相關資訊，請參閱[AWS Lambda 開發人員指南](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)。
建立推薦者模型的 Amazon Pinpoint 組態後，可將模型中的建議，加入從行銷活動和旅程傳送的訊息。您將使用包含建議屬性訊息變數之訊息範本來執行這項操作。*建議的屬性*是用來存放建議資料的動態端點或使用者屬性。您可以在建立推薦者模型的組態時定義這些屬性。
您可以針對下列訊息範本類型中的建議屬性使用變數：
+ 電子郵件範本，適用於您從行銷活動或旅程傳送的電子郵件訊息。
+ 推播通知範本，用於您從行銷活動傳送的推播通知。
+ SMS 範本，適用於您從行銷活動傳送的 SMS 文字訊息。
如需使用推薦者模型搭配 Amazon Pinpoint 的詳細資訊，請參閱 *Amazon Pinpoint 使用者指南*中的[機器學習模型](https://docs.aws.amazon.com/pinpoint/latest/userguide/ml-models.html)。
如果將 Amazon Pinpoint 設為調用 Lambda 函數以處理建議資料，Amazon Pinpoint 每次在行銷活動或旅程的訊息中傳送個人化建議時，都會執行以下一般任務：
1. 評估和處理訊息和訊息範本的組態設定和內容。
1. 決定訊息範本連線到推薦人模型。
1. 評估連接和使用模型的組態設定。這些是由模型的[推薦者模型](https://docs.aws.amazon.com/pinpoint/latest/apireference/recommenders-recommender-id.html)資源所定義。
1. 為模型組態設定定義的推薦屬性偵測一或多個訊息變數。
1. 從您在模型組態設定中指定的 Amazon Personalize 行銷活動，擷取建議資料。它使用 Amazon Personalize Runtime API 的 [GetRecommendations](https://docs.aws.amazon.com/personalize/latest/dg/API_RS_GetRecommendations.html) 操作執行這項任務。
1. 將適當的建議資料新增至每個訊息收件人的動態建議屬性 (`RecommendationItems`)。
1. 調用 Lambda 函數，並將每個收件人的建議資料傳送到 Lambda 函數進行處理。
該資料會以 JSON 物件的形式傳送，其中包含每個收件人的端點定義。每個端點定義都包含一個 `RecommendationItems` 欄位，內含 1-5 個值的已排序陣列。陣列中值的數量依模型的組態設定而定。
1. 等待 Lambda 函數處理資料並傳回結果。
結果是其中包含每個收件人更新的端點定義 JSON 物件。每個更新的端點定義都包含一個新 `Recommendations` 物件。此物件包含 1-10 個欄位，每個欄位對應您在模型組態設定中定義的自訂推薦屬性。這些欄位都會存放端點的增強建議資料。
1. 使用每個收件人更新的端點定義，以該收件人的適當值取代每個訊息變數。
1. 傳送訊息版本，其中包含每個訊息收件人的個人化建議。
若要以此方式自訂和增強建議，請先建立一個 Lambda 函數來處理 Amazon Pinpoint 傳送的端點定義，然後傳回更新的端點定義。接著為 Lambda 函數指派 Lambda 函數政策，並授權 Amazon Pinpoint 調用 Lambda 函數。接著在 Amazon Pinpoint 中設定推薦者模型。在您設定模型時，請指定要叫用的函數，並定義要使用的建議屬性。
# 為 Amazon Pinpoint 建立 Lambda 函數以叫用推薦者模型
若要了解如何建立 Lambda 函數，請參閱 *AWS Lambda 開發人員指南*中的[入門](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)。在您設計和開發函數時，請牢記以下要求和準則。
## 輸入事件資料
Amazon Pinpoint 為推薦者模型調用 Lambda 函數時，會傳送一個承載，內含傳送訊息的行銷活動或旅程的組態和其他設定。承載包括一個 `Endpoints` 物件，它是一種對應，可將端點 ID 與訊息收件人的端點定義產生關聯。
端點定義使用的結構，是由 Amazon Pinpoint API 的[端點](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-endpoints-endpoint-id.html)資源定義。不過，它們也包含一個名為 `RecommendationItems` 的動態建議屬性欄位。此 `RecommendationItems` 欄位包含一或多個該端點的推薦項目，由 Amazon Personalize 行銷活動傳回。此欄位的值，是一個包含 1-5 個推薦項目 (以字串表示) 的已排序陣組。陣列中的項目數，視您為每個端點或使用者設定 Amazon Pinpoint 要擷取的推薦項目數而定。
例如：
```
"Endpoints": {
"endpointIDexample-1":{
"ChannelType":"EMAIL",
"Address":"sofiam@example.com",
"EndpointStatus":"ACTIVE",
"OptOut":"NONE",
"EffectiveDate":"2020-02-26T18:56:24.875Z",
"Attributes":{
"AddressType":[
"primary"
]
},
"User":{
"UserId":"SofiaMartínez",
"UserAttributes":{
"LastName":[
"Martínez"
],
"FirstName":[
"Sofia"
],
"Neighborhood":[
"East Bay"
]
}
},
"RecommendationItems":[
"1815",
"2009",
"1527"
],
"CreationDate":"2020-02-26T18:56:24.875Z"
},
"endpointIDexample-2":{
"ChannelType":"EMAIL",
"Address":"alejandror@example.com",
"EndpointStatus":"ACTIVE",
"OptOut":"NONE",
"EffectiveDate":"2020-02-26T18:56:24.897Z",
"Attributes":{
"AddressType":[
"primary"
]
},
"User":{
"UserId":"AlejandroRosalez",
"UserAttributes":{
"LastName ":[
"Rosalez"
],
"FirstName":[
"Alejandro"
],
"Neighborhood":[
"West Bay"
]
}
},
"RecommendationItems":[
"1210",
"6542",
"4582"
],
"CreationDate":"2020-02-26T18:56:24.897Z"
}
}
```
在上述的範例中，相關的 Amazon Pinpoint 設定如下：
+ 推薦者模型是設定為擷取每個端點或使用者的三個建議項目。(`RecommendationsPerMessage` 屬性的值設為 `3`) Amazon Pinpoint 使用此設定，為每個端點或使用者只擷取並新增第一個、第二個和第三個推薦項目。
+ 該專案已設定為使用自訂使用者屬性，可存放每個使用者的名字、姓氏和他們所在的社區。(`UserAttributes` 物件包含這些屬性的值)。
+ 該專案已設定為使用自訂端點屬性 (`AddressType`)，指出端點是否為使用者偏好的地址 (通道)，以接收來自專案的訊息。(`Attributes` 物件包含此屬性的值)。
Amazon Pinpoint 調用 Lambda 函數，並將此承載當作事件資料傳送時， AWS Lambda 將資料傳遞給 Lambda 函數進行處理。
每個承載最多可包含 50 個端點的資料。如果客群包含超過 50 個端點，Amazon Pinpoint 會重複調用函數，一次最多呼叫 50 個端點，直到該函數處理完所有資料為止。
## 回應資料和需求
設計和開發 Lambda 函數時，請記住[機器學習模型的配額](quotas.md#quotas-ML-models)。如果函數不符合這些配額定義的條件，Amazon Pinpoint 將無法處理並傳送訊息。
同時請記住下列需求：
+ 函數必須以輸入事件資料所提供的相同格式傳回更新的端點定義。
+ 每個更新的端點定義可以包含 1–10 個端點或使用者的自訂建議屬性。這些屬性的名稱，必須符合您在 Amazon Pinpoint 中設定推薦者模型時所指定的屬性名稱。
+ 針對每一個端點或使用者，所有自訂建議屬性都必須以單一的 `Recommendations` 物件回傳。此需求有助於確保不會發生命名衝突。您可以將 `Recommendations` 物件新增至端點定義中的任何位置。
+ 每個自訂建議屬性的值必須是字串 (單一值) 或字串陣列 (多個值)。如果值是字串陣列，建議您維持 Amazon Personalize 傳回的推薦項目順序，如 `RecommendationItems` 欄位所示。否則，您的內容可能無法反映模型對端點或使用者的預測。
+ 函數不應該修改事件資料中的其他元素，包括端點或使用者的其他屬性值。它應該只新增並傳回自訂建議屬性的值。Amazon Pinpoint 不會接受函數回應中任何其他值的更新。
+ 函數必須託管在與叫用函數的 Amazon Pinpoint 專案相同的 AWS 區域中。如果函數和專案不在同一個區域，Amazon Pinpoint 無法將事件資料傳送到該函數。
如果不符合上述任一要求，Amazon Pinpoint 將無法處理訊息，並將訊息傳送至一個或多個端點。這可能會導致行銷活動或旅程活動失敗。
最後，我們建議您為函數保留 256 個並行執行。
整體而言，您的 Lambda 函數應處理 Amazon Pinpoint 傳送的事件資料，並傳回修改後的端點定義。透過在 `Endpoints` 物件中的逐一查看每個端點，並針對每個端點建立和設定您要使用的自訂建議屬性值來完成此操作。下列範例處理常式 (使用 Python 編寫並繼續上述的輸入事件資料範例) 顯示了這一點：
```
import json
import string
def lambda_handler(event, context):
print("Received event: " + json.dumps(event))
print("Received context: " + str(context))
segment_endpoints = event["Endpoints"]
new_segment = dict()
for endpoint_id in segment_endpoints.keys():
endpoint = segment_endpoints[endpoint_id]
if supported_endpoint(endpoint):
new_segment[endpoint_id] = add_recommendation(endpoint)
print("Returning endpoints: " + json.dumps(new_segment))
return new_segment
def supported_endpoint(endpoint):
return True
def add_recommendation(endpoint):
endpoint["Recommendations"] = dict()
customTitleList = list()
customGenreList = list()
for i,item in enumerate(endpoint["RecommendationItems"]):
item = int(item)
if item == 1210:
customTitleList.insert(i, "Hanna")
customGenreList.insert(i, "Action")
elif item == 1527:
customTitleList.insert(i, "Catastrophe")
customGenreList.insert(i, "Comedy")
elif item == 1815:
customTitleList.insert(i, "Fleabag")
customGenreList.insert(i, "Comedy")
elif item == 2009:
customTitleList.insert(i, "Late Night")
customGenreList.insert(i, "Drama")
elif item == 4582:
customTitleList.insert(i, "Agatha Christie\'s The ABC Murders")
customGenreList.insert(i, "Crime")
elif item == 6542:
customTitleList.insert(i, "Hunters")
customGenreList.insert(i, "Drama")
endpoint["Recommendations"]["Title"] = customTitleList
endpoint["Recommendations"]["Genre"] = customGenreList
return endpoint
```
在上述範例中， 會將事件資料 AWS Lambda 傳遞給處理常式做為 `event` 參數。處理常式會逐一查看 `Endpoints` 物件中的每個端點，並為名為 `Recommendations.Title` 和 `Recommendations.Genre` 的自訂建議屬性設定值。`return` 陳述式會將每個更新的端點定義傳回 Amazon Pinpoint。
繼續先前的輸入事件資料範例，更新的端點定義為：
```
"Endpoints":{
"endpointIDexample-1":{
"ChannelType":"EMAIL",
"Address":"sofiam@example.com",
"EndpointStatus":"ACTIVE",
"OptOut":"NONE",
"EffectiveDate":"2020-02-26T18:56:24.875Z",
"Attributes":{
"AddressType":[
"primary"
]
},
"User":{
"UserId":"SofiaMartínez",
"UserAttributes":{
"LastName":[
"Martínez"
],
"FirstName":[
"Sofia"
],
"Neighborhood":[
"East Bay"
]
}
},
"RecommendationItems":[
"1815",
"2009",
"1527"
],
"CreationDate":"2020-02-26T18:56:24.875Z",
"Recommendations":{
"Title":[
"Fleabag",
"Late Night",
"Catastrophe"
],
"Genre":[
"Comedy",
"Comedy",
"Comedy"
]
}
},
"endpointIDexample-2":{
"ChannelType":"EMAIL",
"Address":"alejandror@example.com",
"EndpointStatus":"ACTIVE",
"OptOut":"NONE",
"EffectiveDate":"2020-02-26T18:56:24.897Z",
"Attributes":{
"AddressType":[
"primary"
]
},
"User":{
"UserId":"AlejandroRosalez",
"UserAttributes":{
"LastName ":[
"Rosalez"
],
"FirstName":[
"Alejandro"
],
"Neighborhood":[
"West Bay"
]
}
},
"RecommendationItems":[
"1210",
"6542",
"4582"
],
"CreationDate":"2020-02-26T18:56:24.897Z",
"Recommendations":{
"Title":[
"Hanna",
"Hunters",
"Agatha Christie\'s The ABC Murders"
],
"Genre":[
"Action",
"Drama",
"Crime"
]
}
}
}
```
在上述範例中，函數會修改接收並傳回結果的 `Endpoints` 物件。每個端點的 `Endpoint` 物件現在包含一個新的 `Recommendations` 物件，其中包含 `Title` 和 `Genre` 欄位。每個欄位都存放了三個值 (作為字串) 的排序陣列，其中每個值都會為 `RecommendationItems` 欄位中對應的建議項目提供增強內容。
# 指派 Lambda 函數政策以授權 Amazon Pinpoint 處理建議資料
使用 Lambda 函數處理建議資料之前，必須先授權 Amazon Pinpoint 調用 Lambda 函數。若要授予調用許可，請將 Lambda 函數政策指派給 Lambda 函數。*Lambda 函數政策*是資源型許可政策，指定哪些實體可以使用函數，以及這些實體可以執行哪些動作。詳情請參閱 *AWS Lambda 開發人員指南*中的[為 AWS Lambda使用資源型政策](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)。
*以下範例政策允許 Amazon Pinpoint 服務主體針對特定 Amazon Pinpoint 專案 (projectId*) 中的特定 Amazon Pinpoint 行銷活動 (*campaignId*) 使用 `lambda:InvokeFunction` 動作：
```
{
"Sid": "sid",
"Effect": "Allow",
"Principal": {
"Service": "pinpoint.us-east-1.amazonaws.com"
},
"Action": "lambda:InvokeFunction",
"Resource": "{arn:aws:lambda:us-east-1:accountId:function:function-name}",
"Condition": {
"ArnLike": {
"AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:accountId:recommenders/*"
}
}
}
```
您的函數政策需要包含 `AWS:SourceArn` 金鑰的 `Condition` 區塊。此金鑰指定了允許呼叫函數的資源。在前面的範例中，該政策允許一個特定的行銷活動叫用該函數。
您也可以撰寫政策，讓 Amazon Pinpoint 服務主體針對特定 Amazon Pinpoint 專案 (*projectId*) 中的所有行銷活動和旅程使用 `lambda:InvokeFunction` 動作。此如以下範例政策所示：
```
{
"Sid": "sid",
"Effect": "Allow",
"Principal": {
"Service": "pinpoint.us-east-1.amazonaws.com"
},
"Action": "lambda:InvokeFunction",
"Resource": "{arn:aws:lambda:us-east-1:accountId:function:function-name}",
"Condition": {
"ArnLike": {
"AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:accountId:recommenders/*"
}
}
}
```
與第一個範例不同，這個例子 `Condition` 區塊中的 `AWS:SourceArn` 金鑰允許一個特定的專案叫用該函數。此許可適用於專案中的所有行銷活動和旅程。
若要編寫較一般的政策，您可以使用多字元比對萬用字元 (\$1)。例如您可以使用以下 `Condition` 區塊，允許任何 Amazon Pinpoint 專案調用函數：
```
"Condition": {
"ArnLike": {
"AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:accountId:recommenders/*"
}
}
```
如果想將 Lambda 函數用於 Amazon Pinpoint 帳戶的所有專案，建議您依照上述方式設定政策的 `Condition` 區塊。不過，最佳實務是您應該建立僅包含在特定資源執行特定動作所需許可的政策。
## 授權 Amazon Pinpoint 使用 AWS CLI 和 Lambda add-permission 命令叫用 Lambda 函數
將 Lambda 函數政策指派給函數之後，您可以新增許可，允許 Amazon Pinpoint 叫用特定專案、行銷活動或旅程的函數。您可以使用 AWS Command Line Interface (AWS CLI) 和 Lambda [https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html)命令來執行此操作。以下範例顯示了如何為特定專案 (*projectId*) 執行此操作：
```
$ aws lambda add-permission \
--function-name function-name \
--statement-id sid \
--action lambda:InvokeFunction \
--principal pinpoint.us-east-1.amazonaws.com \
--source-arn arn:aws:mobiletargeting:us-east-1:accountId:recommenders/*
```
上述範例格式適用於 Unix、Linux 和 macOS。若使用 Microsoft Windows，請使用插入符號(^) 取代反斜線 (\$1) 行接續字元。
如果此命令成功執行，您會看到類似如下的輸出：
```
{
"Statement": "{\"Sid\":\"sid\",
\"Effect\":\"Allow\",
\"Principal\":{\"Service\":\"pinpoint.us-east-1.amazonaws.com\"},
\"Action\":\"lambda:InvokeFunction\",
\"Resource\":\"arn:aws:lambda:us-east-1:111122223333:function:function-name\",
\"Condition\":
{\"ArnLike\":
{\"AWS:SourceArn\":
\"arn:aws:mobiletargeting:us-east-1:111122223333:recommenders/*\"}}}"
}
```
`Statement` 值是陳述式的 JSON 字串版本，且已新增至 Lambda 函數政策。
## 設定 Amazon Pinpoint 以叫用建議者模型的 Lambda 函數
若要將 Amazon Pinpoint 設為可調用推薦者統模型的 Lambda 函數，請為該模型指定以下 Lambda 專用的組態設定：
+ `RecommendationTransformerUri` – 此屬性指定 Lambda 函數的名稱或 Amazon Resource Name (ARN)。
+ `Attributes` – 此物件是一個對應，定義了函數新增到每個端點定義的自訂建議屬性。這些屬性中的每一個都可以做為訊息範本中的訊息變數使用。
使用 Amazon Pinpoint API 的[推薦者統模型](https://docs.aws.amazon.com/pinpoint/latest/apireference/recommenders.html)資源 (若已為模型建立組態)，或 Amazon Pinpoint API 的[推薦者統模型](https://docs.aws.amazon.com/pinpoint/latest/apireference/recommenders-recommender-id.html)資源 (若已更新模型的組態)，可指定這些設定。您也可以使用 Amazon Pinpoint 主控台定義這些設定。
如需使用推薦者模型搭配 Amazon Pinpoint 的詳細資訊，請參閱 *Amazon Pinpoint 使用者指南*中的[機器學習模型](https://docs.aws.amazon.com/pinpoint/latest/userguide/ml-models.html)。