**支援結束通知：**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 建立 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` 欄位中對應的建議項目提供增強內容。