本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Personalize 個人化 Amazon OpenSearch Service 的結果
若要從 Amazon OpenSearch Service 個人化 OpenSearch 結果，請執行下列動作：
1. **設定 Amazon Personalize** – 如果您尚未設定，請完成 中的步驟[設定 Amazon Personalize](setup.md)，以設定您的登入資料並設定 Amazon Personalize 的許可。您不需要設定 AWS SDKs即可個人化 OpenSearch 結果。
1. **完成 Amazon Personalize 工作流程** – 完成 Amazon Personalize 工作流程以匯入資料、使用 Personalized-Ranking-v2 或 Personalized-Ranking 配方建立解決方案、訓練自訂解決方案版本，並在行銷活動中部署。您必須建立項目互動資料集。使用者資料集和項目資料集是選用的。如需詳細資訊，請參閱[Amazon Personalize 工作流程詳細資訊](personalize-workflow.md)。
1. **設定許可** – 設定許可，以便您可以從 OpenSearch Service 網域存取 Amazon Personalize 資源。如需詳細資訊，請參閱[設定許可](opensearch-granting-access-managed.md)。
1. **安裝 Amazon Personalize Search Ranking 外掛程式** – 此外掛程式會處理與 Amazon Personalize 的通訊，並重新排序結果。如需在 OpenSearch Service 網域上安裝外掛程式的詳細資訊，請參閱 [安裝外掛程式](open-search-install-managed.md)。
1. **設定 Amazon Personalize Search Ranking 外掛程式** – 若要設定外掛程式，請建立搜尋管道。*搜尋管道*是一組請求和回應處理器。當您為外掛程式建立管道時，您可以在`personalized_search_ranking`回應處理器中指定 Amazon Personalize 資源。您也可以設定外掛程式在重新排序結果時提供 Amazon Personalize 結果的權重。如需詳細資訊，請參閱[建立管道](managed-opensearch-plugin-pipeline-example.md)。
1. **將 Amazon Personalize Search Ranking 外掛程式套用至 OpenSearch 查詢** – 使用`personalized_search_ranking`回應處理器設定搜尋管道之後，您就可以將 Amazon Personalize Search Ranking 外掛程式套用至 OpenSearch 查詢，並檢視重新排名的結果。如需將外掛程式套用至 OpenSearch Service 查詢的資訊，請參閱 [套用外掛程式](managed-apply-plugin.md)。
1. **比較結果** – Amazon Personalize Search Ranking 外掛程式會在 OpenSearch 查詢回應中重新排序搜尋結果。它同時考慮來自 Amazon Personalize 的排名和來自 OpenSearch 的排名。若要了解結果的重新排名方式，您可以比較使用個人化和非個人化查詢的結果。如需比較結果與 OpenSearch Service 的相關資訊，請參閱 [比較結果](managed-comparing-results.md)。
1. **監控 Amazon Personalize Search Ranking 外掛程式** – 當您套用 Amazon Personalize Search Ranking 外掛程式來搜尋查詢時，您可以透過取得搜尋管道的指標來監控外掛程式。如需使用 OpenSearch Service 監控外掛程式的資訊，請參閱 [監控外掛程式](managed-monitor.md)。
**Topics**
+ [設定 Amazon OpenSearch Service 許可](opensearch-granting-access-managed.md)
+ [在 OpenSearch Service 網域上安裝 Amazon Personalize Search Ranking 外掛程式](open-search-install-managed.md)
+ [在 Amazon OpenSearch Service 中建立管道](managed-opensearch-plugin-pipeline-example.md)
+ [將外掛程式套用至 Amazon OpenSearch Service 查詢](managed-apply-plugin.md)
+ [將個人化 Amazon OpenSearch Service 結果與結果進行比較，無需個人化](managed-comparing-results.md)
+ [使用 Amazon OpenSearch Service 監控外掛程式](managed-monitor.md)
# 設定 Amazon OpenSearch Service 許可
如果您使用 Amazon OpenSearch Service，您必須能夠從 OpenSearch Service 網域存取 Amazon Personalize 資源。
**若要設定 許可**
1. 視您的資源是否位於相同或不同的帳戶而定，請建立具有存取資源許可的一或多個 IAM 服務角色。
+ 如果您的 OpenSearch Service 和 Amazon Personalize 資源位於同一個帳戶中，您可以為 OpenSearch Service 建立 IAM 服務角色，並授予許可，以從您的 Amazon Personalize 行銷活動取得個人化排名。如需詳細資訊，請參閱[當資源位於相同帳戶時設定許可](service-role-managed.md)。
+ 如果您的 OpenSearch Service 和 Amazon Personalize 資源位於不同的帳戶中，您可以建立兩個 IAM 服務角色。您可以使用 OpenSearch Service 資源在帳戶中建立一個資源，並授予其存取 OpenSearch Service 資源的權限。而且，您可以使用 Amazon Personalize 資源在帳戶中建立一個 ，並授予它從您的 Amazon Personalize 行銷活動取得個人化排名的許可。如需詳細資訊，請參閱[當資源位於不同帳戶時設定許可](configuring-multiple-accounts.md)。
1. 授予存取您為 OpenSearch Service 建立之 IAM 服務角色的 OpenSearch Service 網域`PassRole`許可的使用者或角色。如需詳細資訊，請參閱[設定 Amazon OpenSearch Service 網域安全性](domain-user-managed.md)。
設定許可之後，您就可以在網域上安裝外掛程式。如需詳細資訊，請參閱[安裝外掛程式](open-search-install-managed.md)。
**Topics**
+ [當資源位於相同帳戶時設定許可](service-role-managed.md)
+ [當資源位於不同帳戶時設定許可](configuring-multiple-accounts.md)
+ [設定 Amazon OpenSearch Service 網域安全性](domain-user-managed.md)
# 當資源位於相同帳戶時設定許可
如果您的 OpenSearch Service 和 Amazon Personalize 資源位於相同的帳戶中，您必須為 OpenSearch Service 建立 IAM 服務角色。此角色必須具有從 Amazon Personalize 行銷活動取得個人化排名的許可。以下是授予 OpenSearch Service 服務角色許可，以從您的 Amazon Personalize 行銷活動取得個人化排名的必要條件：
+ 角色的信任政策必須授予 OpenSearch Service 的`AssumeRole`許可。如需信任政策範例，請參閱 [信任政策範例](#opensearch-granting-access-managed-trust-policy)。
+ 該角色必須具有從您的 Amazon Personalize 行銷活動取得個人化排名的許可。如需政策範例，請參閱[許可政策範例](#opensearch-granting-access-managed-permissions-policy)。
如需建立 IAM 角色的資訊，請參閱《[IAM 使用者指南》中的建立 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。 **如需將 IAM 政策連接至角色的資訊，請參閱《[IAM 使用者指南》中的新增和移除 IAM 身分許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 **
為 OpenSearch Service 建立 IAM 服務角色之後，您必須授予存取 OpenSearch Service 網域的使用者或角色 OpenSearch Service 服務角色`PassRole`許可。如需詳細資訊，請參閱[設定 Amazon OpenSearch Service 網域安全性](domain-user-managed.md)。
**Topics**
+ [信任政策範例](#opensearch-granting-access-managed-trust-policy)
+ [許可政策範例](#opensearch-granting-access-managed-permissions-policy)
## 信任政策範例
下列信任政策範例會授予 OpenSearch Service 的`AssumeRole`許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"Service": [
"es.amazonaws.com"
]
}
}]
}
```
------
## 許可政策範例
下列政策範例授予角色從 Amazon Personalize 行銷活動取得個人化排名的最低許可。針對 `Campaign ARN`，指定 Amazon Personalize 行銷活動的 Amazon Resource Name (ARN)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"personalize:GetPersonalizedRanking"
],
"Resource": "arn:aws:personalize:us-east-1:111122223333:campaign/YourResourceId"
}
]
}
```
------
# 當資源位於不同帳戶時設定許可
如果您的 OpenSearch Service 和 Amazon Personalize 資源位於不同的帳戶中，您可以在每個帳戶中建立 IAM 角色，並授予該角色對帳戶中資源的存取權。
**設定多個帳戶的許可**
1. 在存在 Amazon Personalize 行銷活動的帳戶中，建立具有從您的 Amazon Personalize 行銷活動取得個人化排名之許可的 IAM 角色。當您設定外掛程式時，您可以在`personalized_search_ranking`回應處理器的 `external_account_iam_role_arn` 參數中指定此角色的 ARN。如需詳細資訊，請參閱[在 Amazon OpenSearch Service 中建立管道](managed-opensearch-plugin-pipeline-example.md)。
如需政策範例，請參閱[許可政策範例](service-role-managed.md#opensearch-granting-access-managed-permissions-policy)。
1. 在存在 OpenSearch Service 網域的帳戶中，建立具有授予 OpenSearch Service `AssumeRole`許可之信任政策的角色。當您設定外掛程式時，您可以在`personalized_search_ranking`回應處理器的 `iam_role_arn` 參數中指定此角色的 ARN。如需詳細資訊，請參閱[在 Amazon OpenSearch Service 中建立管道](managed-opensearch-plugin-pipeline-example.md)。
如需信任政策範例，請參閱 [信任政策範例](service-role-managed.md#opensearch-granting-access-managed-trust-policy)。
1. 修改每個角色以授予其他角色`AssumeRole`許可。例如，對於可存取 Amazon Personalize 資源的角色，其 IAM 政策會授予具有 OpenSearch Service 網域之帳戶中的角色擔任角色許可，如下所示：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/roleName"
}]
}
```
------
1. 在存在 OpenSearch Service 網域的帳戶中，授予使用者或角色存取您剛建立之 OpenSearch Service 服務角色的 OpenSearch Service 網域`PassRole`許可。如需詳細資訊，請參閱[設定 Amazon OpenSearch Service 網域安全性](domain-user-managed.md)。
# 設定 Amazon OpenSearch Service 網域安全性
若要搭配 OpenSearch Service 使用外掛程式，存取網域的使用者或角色必須具有您剛建立之 [ OpenSearch Service 的 IAM 服務角色](service-role-managed.md)`PassRole`許可。此外，使用者或角色必須具有執行 `es:ESHttpGet`和 `es:ESHttpPut`動作的許可。
如需有關設定 OpenSearch Service 存取權的資訊，請參閱《[Amazon OpenSearch Service 開發人員指南》中的 Amazon OpenSearch Service 中的安全性](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/security.html)。 * OpenSearch * 如需政策範例，請參閱[OpenSearch Service 使用者或角色的政策範例](#opensearch-domain-user-policy-examples)。
## OpenSearch Service 使用者或角色的政策範例
下列 IAM 政策範例會授予您在 中為 OpenSearch Service 建立之 IAM 服務角色的使用者或角色`PassRole`許可[當資源位於相同帳戶時設定許可](service-role-managed.md)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/aws-service-role/opensearchservice.amazonaws.com/AWSServiceRoleForAmazonOpenSearchService"
}
]
}
```
------
下列 IAM 政策授予使用 OpenSearch Service 建立管道和搜尋查詢的最低許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"es:ESHttpGet",
"es:ESHttpPut"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
}
]
}
```
------
# 在 OpenSearch Service 網域上安裝 Amazon Personalize Search Ranking 外掛程式
完成 Amazon Personalize 工作流程並滿足 中列出的要求後[外掛程式需求](plugin-requirements.md)，您就可以在網域上安裝外掛程式。
若要使用外掛程式，請將`Amazon_Personalize_Search_Ranking_Plugin`外掛程式與您的網域建立關聯。外掛程式已預先安裝，您不需要從 Amazon S3 匯入。您建立外掛程式的關聯方式與建立 OpenSearch Service 套件的關聯方式相同。如需有關關聯 OpenSearch Service 套件的資訊，請參閱 [Amazon OpenSearch Service 的自訂套件](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/custom-packages.html#custom-packages-assoc)。
將外掛程式與網域建立關聯之後，您就可以設定外掛程式。您可以透過建立搜尋管道並指定`personalized_search_ranking`回應處理器來設定它。如需詳細資訊，請參閱[建立管道](managed-opensearch-plugin-pipeline-example.md)。
## 有關 Amazon OpenSearch Service 網域的其他資訊
下列資源提供使用 Amazon OpenSearch Service 網域的其他資訊。
+ 如需設定測試網域的簡潔教學課程，請參閱[《Amazon OpenSearch Service 開發人員指南》的「入門」一節中的步驟 1：建立](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gsg.html#gsgcreate-domain) *Amazon OpenSearch Service* 網域。
+ 如需設定 OpenSearch Service 網域的更多詳細步驟，請參閱[建立和管理 Amazon OpenSearch Service 網域](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html)。
+ 如需將少量測試資料上傳至 OpenSearch Service 的簡潔教學課程，請參閱《[Amazon OpenSearch Service 開發人員指南》的「入門」一節中的步驟 2：將資料上傳至 Amazon OpenSearch Service 以進行索引](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gsg.html#gsgupload-data)。 * OpenSearch *
+ 如需擷取資料的完整資訊，請參閱《[Amazon OpenSearch Service 開發人員指南》中的在 Amazon OpenSearch Service 中為資料編製索引](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/indexing.html)。 * OpenSearch *
# 在 Amazon OpenSearch Service 中建立管道
[安裝 Amazon Personalize Search Ranking 外掛程式](open-search-install-managed.md)之後，您就可以透過建立 OpenSearch 搜尋管道來進行設定。
*搜尋管道*是一組請求和回應處理器，會依照您建立它們的順序依序執行。當您為外掛程式建立搜尋管道時，您可以指定`personalized_search_ranking`回應處理器。如需搜尋管道的相關資訊，請參閱[搜尋管道](https://opensearch.org/docs/latest/search-plugins/search-pipelines/index/)。
使用`personalized_search_ranking`回應處理器建立搜尋管道之後，您就可以開始將外掛程式套用至 OpenSearch 查詢。您可以將其套用至 OpenSearch 索引或個別 OpenSearch 查詢。如需詳細資訊，請參閱[套用外掛程式](managed-apply-plugin.md)。
您可以使用下列 Python 程式碼，在 OpenSearch Service 網域上使用`personalized_search_ranking`回應處理器建立搜尋管道。`domain endpoint` 將 取代為您的網域端點 URL。例如：`https://..es-staging.amazonaws.com`。如需每個`personalized_search_ranking`參數的完整說明，請參閱 [`personalized_search_ranking` 回應處理器的欄位](opensearch-plugin-pipeline-fields.md)。
```
import requests
from requests_auth_aws_sigv4 import AWSSigV4
domain_endpoint = 'domain endpoint'
pipeline_name = 'pipeline name'
url = f'{domain_endpoint}/_search/pipeline/{pipeline_name}'
auth = AWSSigV4('es')
headers = {'Content-Type': 'application/json'}
body = {
"description": "A pipeline to apply custom re-ranking from Amazon Personalize",
"response_processors": [
{
"personalized_search_ranking" : {
"campaign_arn" : "Amazon Personalize Campaign ARN",
"item_id_field" : "productId",
"recipe" : "aws-personalized-ranking-v2",
"weight" : "0.3",
"tag" : "personalize-processor",
"iam_role_arn": "Role ARN",
"aws_region": "AWS region",
"ignore_failure": true
}
]
}
try:
response = requests.put(url, auth=auth, json=body, headers=headers, verify=False)
print(response.text)
except Exception as e:
print(f"Error: {e}")
```
# 將外掛程式套用至 Amazon OpenSearch Service 查詢
[建立管道](managed-opensearch-plugin-pipeline-example.md)之後，您就可以將 Amazon Personalize Search Ranking 外掛程式套用至查詢。您可以將 Amazon Personalize Search Ranking 外掛程式套用至索引的所有查詢和回應。您也可以將外掛程式套用至個別的查詢和回應。
+ 您可以使用下列 Python 程式碼，將搜尋管道套用至索引。使用此方法，使用此索引的所有搜尋都會使用 外掛程式將個人化套用至搜尋結果。
```
import requests
from requests_auth_aws_sigv4 import AWSSigV4
domain_endpoint = 'domain endpoint'
index = 'index name'
url = f'{domain_endpoint}/{index}/_settings/'
auth = AWSSigV4('es')
headers = {'Content-Type': 'application/json'}
body = {
"index.search.default_pipeline": "pipeline name"
}
try:
response = requests.put(url, auth=auth, json=body, headers=headers)
print(response.text)
except Exception as e:
print(f"Error: {e}")
```
+ 您可以使用下列 Python 程式碼，將搜尋管道套用至 Toyota 品牌車的個別查詢。
更新程式碼以指定您的網域端點、OpenSearch Service 索引、管道名稱和查詢。針對 `user_id`，指定您要取得搜尋結果的使用者 ID。此使用者必須位於您用來建立 Amazon Personalize 解決方案版本的資料中。如果使用者不存在，Amazon Personalize 會根據其熱門程度對項目進行排名。
對於 `context`，如果您使用內容中繼資料，請提供使用者的內容中繼資料，例如其裝置類型。此 `context` 欄位為選用。如需詳細資訊，請參閱[提高與內容中繼資料的建議相關性](contextual-metadata.md)。
```
import requests
from requests_auth_aws_sigv4 import AWSSigV4
domain_endpoint = 'domain endpoint'
index = 'index name'
url = f'{domain_endpoint}/{index}/_search/'
auth = AWSSigV4('es')
headers = {'Content-Type': 'application/json'}
params = {"search_pipeline": "pipeline-name"}
body = {
"query": {
"multi_match": {
"query": "Toyota",
"fields": ["BRAND"]
}
},
"ext": {
"personalize_request_parameters": {
"user_id": "USER ID",
"context": { "DEVICE" : "mobile phone" }
}
}
}
try:
response = requests.post(url, auth=auth, params=params, json=body, headers=headers, verify=False)
print(response)
except Exception as e:
print(f"Error: {e}")
```
# 將個人化 Amazon OpenSearch Service 結果與結果進行比較，無需個人化
Amazon Personalize Search Ranking 外掛程式會根據來自 Amazon Personalize 的排名和來自 OpenSearch 的排名來重新排列搜尋結果。外掛程式重新排序結果的方式取決於您在管道中設定`personalized_search_ranking`回應處理器的方式。
若要了解結果的排名，您可以使用和不使用個人化來執行查詢，並比較結果。您可以使用下列 Python 程式碼來執行兩個不同的查詢，並將結果輸出至兩個 JSON 檔案。第一個方法會執行使用外掛程式來重新排序結果的查詢。第二個執行的方法會產生結果，而不需要個人化。
```
import json
import requests
from requests_auth_aws_sigv4 import AWSSigV4
# Returns re-ranked OpenSearch results using the Amazon Personalize Search Ranking plugin.
def get_personalized_results(pipeline_name):
url = f'{domain}/{index}/_search/'
auth = AWSSigV4('es')
headers = {'Content-Type': 'application/json'}
params = {"search_pipeline": pipeline_name}
body = {
"query": {
"multi_match": {
"query": "Toyota",
"fields": ["BRAND"]
}
},
"ext": {
"personalize_request_parameters": {
"user_id": "1"
}
}
}
try:
response = requests.post(url, auth=auth, params=params, json=body, headers=headers, verify=False)
except Exception as e:
return f"Error: {e}"
return response.text
# Returns OpenSearch results without personalization.
def get_opensearch_results():
url = f'{domain}/{index}/_search/'
auth = AWSSigV4('es')
headers = {'Content-Type': 'application/json'}
body = {
"query": {
"multi_match": {
"query": "Toyota",
"fields": ["BRAND"]
}
}
}
try:
response = requests.post(url, auth=auth, json=body, headers=headers, verify=False)
except Exception as e:
return f"Error: {e}"
return response.text
def print_results(file_name, results):
results_file = open(file_name, 'w')
results_file.write(json.dumps(results, indent=4))
results_file.close()
# specify domain endpoint
domain = "DOMAIN_ENDPOINT"
# specify the region where you created your Amazon Personalize resources and Amazon OpenSearch domain
aws_region = "REGION"
# specify the name of the pipeline that uses the Amazon Personalize plugin
pipeline_name = "PIPELINE_NAME"
# specify your Amazon OpenSearch index
index = "INDEX"
# specify names for json files for comparison
personalized_results_file = "personalized_results.json"
opensearch_results_file = "opensearch_results.json"
# get personalized results
personalized_results = json.loads(get_personalized_results(pipeline_name))
# get OpenSearch results without personalization
opensearch_results = json.loads(get_opensearch_results())
# print results to files
print_results(personalized_results_file, personalized_results)
print_results(opensearch_results_file, opensearch_results)
```
# 使用 Amazon OpenSearch Service 監控外掛程式
當您將 Amazon Personalize Search Ranking 外掛程式套用至 OpenSearch 查詢時，您可以透過取得搜尋管道的指標來監控外掛程式。管道指標包括統計資料，例如`personalized_search_ranking`回應處理器的失敗請求數。
如果您使用 OpenSearch Service，您可以透過 Amazon CloudWatch 中的指標來監控外掛程式。如需詳細資訊，請參閱[監控 Amazon OpenSearch Service 網域](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/monitoring.html)。
您可以使用下列 Python 程式碼來取得所有管道的指標。如需管道指標的範例，請參閱 [管道指標範例](monitor-response.md)。
```
import requests
from requests_auth_aws_sigv4 import AWSSigV4
domain_endpoint = 'domain endpoint'
url = f'{domain_endpoint}/_nodes/stats/search_pipeline'
auth = AWSSigV4('es')
headers = {'Content-Type': 'application/json'}
try:
response = requests.get(url, auth=auth, headers=headers, verify=False)
print(response.text)
except Exception as e:
print(f"Error: {e}")
```