**支援終止通知：**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 最終使用者傳訊支援。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 AWS Lambda 函數自訂 Amazon Pinpoint 客群
| |
| --- |
| 這是公共測試版中某個功能的預先發布文件。內容可能變動。 |
您可以使用 AWS Lambda 來量身打造 Amazon Pinpoint 行銷活動如何吸引目標受眾。使用 AWS Lambda，您可以在 Amazon Pinpoint 傳送行銷活動訊息的那一刻修改行銷活動的客群。
AWS Lambda 是一種運算服務，您可以用來執行程式碼，而無需佈建或管理伺服器。您可以封裝程式碼，並以 Lambda 函數的形式上傳至 *Lambda*。Lambda 在調用函數時會執行函數，這可由您手動完成，也可以根據事件自動完成。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》[https://docs.aws.amazon.com/lambda/latest/dg/welcome.html](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)。
若要將 Lambda 函數指派給行銷活動，可以使用 Amazon Pinpoint API 中的[行銷活動](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id.html)資源，定義行銷活動的 `CampaignHook` 設定。這些設定包括 Lambda 函數名稱，以及 `CampaignHook` 模式，該模式指定 Amazon Pinpoint 是否接收函數的回傳值。
您指派給行銷活動的 Lambda 函數稱為 Amazon Pinpoint *擴充功能*。
定義 `CampaignHook` 設定後，Amazon Pinpoint 會在執行行銷活動時，自動調用 Lambda 函數，然後才傳送行銷活動訊息。Amazon Pinpoint 調用該函數時，會提供訊息交付的相關*事件資料*。此資料包括行銷活動的客群，也就是 Amazon Pinpoint 傳送訊息的目的地端點的清單。
如果將 `CampaignHook` 模式設為 `FILTER`，Amazon Pinpoint 在傳送訊息之前，允許該函數修改和傳回客群。例如該函數可能使用包含 Amazon Pinpoint 外部來源的資料的屬性，更新端點定義。或者，該函數可能根據您的函數程式碼中的條件來移除特定端點，以篩選客群。Amazon Pinpoint 收到您函數修改過的客群後，會使用行銷活動的交付管道，將訊息傳送到客群的每個端點。
透過使用 處理您的客群 AWS Lambda，您可以更好地控制傳送訊息的對象以及這些訊息包含的內容。您可以在傳送行銷活動訊息時，即時修改您的行銷活動。篩選客群可讓您吸引更嚴格定義的一部分客群。新增或更新端點屬性也能讓您提供用於訊息變數的新資料。
**注意**
您也可以使用 `CampaignHook` 設定，指派要處理訊息交付的 Lambda 函數。若要透過 Amazon Pinpoint 不支援的自訂頻道 (例如社群媒體平台) 傳遞訊息，這類函數很有用。如需詳細資訊，請參閱[使用 Webhook 或 Lambda 函數在 Amazon Pinpoint 中建立自訂頻道](channels-custom.md)。
使用 Amazon Pinpoint 調用 Lambda 勾點時，Lambda 函數也必須位於與 Amazon Pinpoint 專案相同的區域。
若要使用 修改行銷活動客群 AWS Lambda，請先建立 函數來處理 Amazon Pinpoint 傳送的事件資料，並傳回修改過的客群。接著指派 Lambda 函數政策，以授權 Amazon Pinpoint 調用函數。最後，透過定義 `CampaignHook` 設定來將函數指派給一或多個行銷活動。
如需更多程式碼範例，請參閱[程式碼範例](https://docs.aws.amazon.com/pinpoint/latest/developerguide/service_code_examples.html)。
## 事件資料
Amazon Pinpoint 調用 Lambda 函數時，會提供以下承載當作事件資料：
```
{
"MessageConfiguration": {Message configuration}
"ApplicationId": ApplicationId,
"CampaignId": CampaignId,
"TreatmentId": TreatmentId,
"ActivityId": ActivityId,
"ScheduledTime": Scheduled Time,
"Endpoints": {
EndpointId: {Endpoint definition}
. . .
}
}
```
AWS Lambda 會將事件資料傳遞至您的函數程式碼。事件資料可提供以下屬性：
+ `MessageConfiguration` – 其結構與 Amazon Pinpoint API 中[訊息](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-messages.html)資源的 `DirectMessageConfiguration` 物件相同。
+ `ApplicationId` – 行銷活動所屬的 Amazon Pinpoint 專案的 ID。
+ `CampaignId` – 調用函數的 Amazon Pinpoint 行銷活動的 ID。
+ `TreatmentId` – 用於 A/B 測試的行銷活動版本的 ID。
+ `ActivityId` – 行銷活動正在執行的活動的 ID。
+ `ScheduledTime` – 交付行銷活動訊息的日期和時間 (ISO 8601 格式)。
+ `Endpoints` – 將端點 ID 與端點定義建立關聯的對應。每個事件資料承載包含最多 50 個端點。如果行銷活動客群包含超過 50 個端點，Amazon Pinpoint 會重複調用函數，一次最多呼叫 50 個端點，直到所有端點處理完畢為止。
## 建立 Lambda 函式
若要了解如何建立 Lambda 函數，請參閱 *AWS Lambda 開發人員指南*中的[入門](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)。建立函數時，請注意以下會造成訊息交付失敗的條件：
+ Lambda 函數超過 15 秒才傳回修改過的客群。
+ Amazon Pinpoint 不能對函數的回傳值解碼。
+ 此函數需要 Amazon Pinpoint 嘗試 3 次以上，才能成功調用。
Amazon Pinpoint 只接受函數傳回值中的端點定義。函數無法修改事件資料中的其他元素。
### Lambda 函數範例
您的 Lambda 函數處理 Amazon Pinpoint 傳送的事件資料，並傳回修改後的端點，如以下在 Node.js 中編寫的範例處理程序所示：
```
'use strict';
exports.handler = (event, context, callback) => {
for (var key in event.Endpoints) {
if (event.Endpoints.hasOwnProperty(key)) {
var endpoint = event.Endpoints[key];
var attr = endpoint.Attributes;
if (!attr) {
attr = {};
endpoint.Attributes = attr;
}
attr["CreditScore"] = [ Math.floor(Math.random() * 200) + 650];
}
}
console.log("Received event:", JSON.stringify(event, null, 2));
callback(null, event.Endpoints);
};
```
Lambda 將事件資料當作為 `event` 參數，傳遞給處理常式。
在這個範例中，處理常式會逐一查看 `event.Endpoints` 物件中的每個端點，並將新的屬性 `CreditScore` 新增到端點。`CreditScore` 屬性的值只是隨機數字。
`console.log()` 陳述式會將事件記錄在 CloudWatch Logs 中。
`callback()` 陳述式會將修改過的端點傳回 Amazon Pinpoint。一般而言，`callback` 參數在 Node.js Lambda 函數中並非必要，但在此情境中則是必要，因為 Lambda 函數必須將更新的端點傳回 Amazon Pinpoint。
您的函數必須以事件資料提供的相同格式來傳回端點，這是將端點 ID 與端點定義建立關聯的映射，如下列範例所示：
```
{
"eqmj8wpxszeqy/b3vch04sn41yw": {
"ChannelType": "GCM",
"Address": "4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c",
"EndpointStatus": "ACTIVE",
"OptOut": "NONE",
"Demographic": {
"Make": "android"
},
"EffectiveDate": "2017-11-02T21:26:48.598Z",
"User": {}
},
"idrexqqtn8sbwfex0ouscod0yto": {
"ChannelType": "APNS",
"Address": "1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f",
"EndpointStatus": "ACTIVE",
"OptOut": "NONE",
"Demographic": {
"Make": "apple"
},
"EffectiveDate": "2017-11-02T21:26:48.598Z",
"User": {}
}
}
```
範例函數會修改並傳回事件資料中收到的 `event.Endpoints` 物件。
在您傳回的端點定義中，您可以選擇性包含 `TitleOverride` 和 `BodyOverride` 屬性。
**注意**
您使用此解決方案傳送訊息時，只有在端點的 `ChannelType` 屬性值是 `ADM`、`APNS`、`APNS_SANDBOX`、`APNS_VOIP`、`APNS_VOIP_SANDBOX`、`BAIDU`、`GCM` 或 `SMS` 時，Amazon Pinpoint 才會採用 `TitleOverride` 和 `BodyOverride` 屬性。
若端點的 `ChannelType` 屬性值是 `EMAIL`，Amazon Pinpoint **不會**採用這些屬性。
## 指派 Lambda 函數政策
使用 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 服務主體對特定行銷活動 (*campaign-id*) 使用 `lambda:InvokeFunction` 動作的許可：
```
{
"Sid": "sid",
"Effect": "Allow",
"Principal": {
"Service": "pinpoint.us-east-1.amazonaws.com"
},
"Action": "lambda:InvokeFunction",
"Resource": "{arn:aws:lambda:us-east-1:account-id:function:function-name}",
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "111122223333"
},
"ArnLike": {
"AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/campaign-id"
}
}
}
```
您的函數政策需要 `Condition` 區塊，其包含一個 `AWS:SourceArn` 金鑰。此程式碼指明允許哪個 Amazon Pinpoint 行銷活動調用函數。在此範例中，政策會授予僅單一行銷活動的許可。`Condition` 區塊也必須包含 `AWS:SourceAccount`金鑰，以控制哪些 AWS 帳戶可以叫用 動作。
若要編寫較一般的政策，請使用多字元比對萬用字元 (\$1)。例如您可以使用以下 `Condition` 區塊，允許特定 Amazon Pinpoint 專案 (*application-id*) 中的任何行銷活動調用該函數：
```
...
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "111122223333"
},
"ArnLike": {
"AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/*"
}
}
...
```
如果您要將 Lambda 函數設成專案中所有行銷活動的預設函數，建議您以上述方式設定政策的 `Condition` 區塊。如需將 Lambda 函數設為專案中所有行銷活動的預設函數的相關資訊，請參閱 [將 Lambda 函數指派給行銷活動](#segments-dynamic-assign)。
### 授予 Amazon Pinpoint 調用許可
您可以使用 AWS Command Line Interface (AWS CLI) 將許可新增至指派給 Lambda 函數的 Lambda 函數政策。若要允許 Amazon Pinpoint 調用特定行銷活動的函數，請使用 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) 命令，如以下範例所示：
```
$ aws lambda add-permission \
> --function-name function-name \
> --statement-id sid \
> --action lambda:InvokeFunction \
> --principal pinpoint.us-east-1.amazonaws.com \
> --source-account 111122223333
> --source-arn arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/campaign-id
```
您可以使用 AWS CLI中的 [get-campaigns](https://docs.aws.amazon.com/cli/latest/reference/pinpoint/get-campaigns.html) 命令，尋找您的行銷活動 ID。您也可以使用 [get-apps](https://docs.aws.amazon.com/cli/latest/reference/pinpoint/get-apps.html) 命令，尋找您的應用程式 ID。
當您執行 Lambda `add-permission` 命令時，Lambda 會傳回以下輸出：
```
{
"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:apps/application-id/campaigns/campaign-id\"}}
{\"StringEquals\":
{\"AWS:SourceAccount\":
\"111122223333\"}}}
}
```
`Statement` 值是陳述式的 JSON 字串版本，且已新增至 Lambda 函數政策。
## 將 Lambda 函數指派給行銷活動
您可以將 Lambda 函數指派給個別 Amazon Pinpoint 行銷活動。或者，您可以將 Lambda 函數設為專案中所有行銷活動的預設值 (個別指派函數的行銷活動除外)。
若要將 Lambda 函數指派給個別行銷活動，請使用 Amazon Pinpoint API 建立或更新 [https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns.html](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns.html) 物件，以及定義其 `CampaignHook` 屬性。若要將 Lambda 函數設為專案中所有行銷活動的預設值，請建立或更新該專案的 [https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-settings.html](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-settings.html) 資源，並定義其 `CampaignHook` 物件。
在這兩種情況下，設定下列 `CampaignHook` 屬性：
+ `LambdaFunctionName` – Amazon Pinpoint 傳送行銷活動訊息之前，調用的 Lambda 函數的名稱或 ARN。
+ `Mode` – 設為 `FILTER`。在此模式下，Amazon Pinpoint 調用函數並等待函數傳回修改過的端點。等到收到端點，Amazon Pinpoint 再傳送訊息。Amazon Pinpoint 等待最多 15 秒，才確認訊息交付失敗。
Amazon Pinpoint 在傳送行銷活動訊息之前，會使用為行銷活動定義的 `CampaignHook` 設定，調用指定的 Lambda 函數。Amazon Pinpoint 等待從函數接收修改過的端點。如果 Amazon Pinpoint 收到已更新的端點，會使用已更新的端點資料，繼續訊息交付。