本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 API 操作中使用 Amazon Verified Permissions 政策存放區別名
任何接受 [IsAuthorized](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorized.html) [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)和 [GetPolicyStore](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_GetPolicyStore.html) 等`policyStoreId`參數的 Amazon Verified Permissions 操作，都可以接受政策存放區別名名稱來取代政策存放區 ID。
**重要**
當您使用政策存放區別名做為`policyStoreId`參數的值時，必須包含 `policy-store-alias/`字首。例如，使用 `policy-store-alias/example-policy-store`，而非 `example-policy-store`。
## 在操作中使用政策存放區別名
下列`IsAuthorized`命令使用具有 名稱的政策存放區別名`example-policy-store`來識別政策存放區。
------
#### [ AWS CLI ]
```
$ aws verifiedpermissions is-authorized \
--policy-store-id policy-store-alias/example-policy-store \
--principal entityType=User,entityId=alice \
--action actionType=Action,actionId=view \
--resource entityType=Photo,entityId=photo123
```
------
**注意**
您無法使用政策存放區別名取代 [DeletePolicyStore](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_DeletePolicyStore.html) 操作的 `policyStoreId` 欄位。
## 使用跨政策存放區別名 AWS 區域
其中一個最強大的別名用途是在多個 AWS 區域中執行之應用程式中使用。例如，您可能有一個全域應用程式，在每個區域中使用不同的政策存放區。
+ 在 us-east-1 中，您想要使用 `PSEXAMPLEabcdefg111111`。
+ 在 eu-west-1 中，您想要使用 `PSEXAMPLEabcdefg222222`。
您可以在每個區域中建立不同的應用程式版本，或使用字典或切換陳述式為每個區域選取正確的政策存放區。但是，在每個區域中建立具有相同政策存放區別名的政策存放區別名會更為容易。請記住，政策存放區別名名稱區分大小寫。
------
#### [ AWS CLI ]
```
$ aws --region us-east-1 verifiedpermissions create-policy-store-alias \
--alias-name policy-store-alias/my-app \
--policy-store-id PSEXAMPLEabcdefg111111
$ aws --region eu-west-1 verifiedpermissions create-policy-store-alias \
--alias-name policy-store-alias/my-app \
--policy-store-id PSEXAMPLEabcdefg222222
```
------
然後，在您的程式碼中使用政策存放區別名。當您的程式碼在每個區域中執行時，政策存放區別名會參考其在該區域中相關聯的政策存放區。
------
#### [ AWS CLI ]
```
$ aws verifiedpermissions is-authorized \
--policy-store-id policy-store-alias/my-app \
--principal entityType=User,entityId=alice \
--action actionType=Action,actionId=view \
--resource entityType=Photo,entityId=photo123
```
------
不過，存在刪除政策存放區別名的風險。在這種情況下，應用程式使用政策存放區別名的嘗試將會失敗，您可能需要重新建立或更新政策存放區別名。若要降低此風險，請謹慎授予委託人許可，以管理您在應用程式中使用的政策存放區別名。
## 政策存放區別名不是流量控制機制
政策存放區別名是政策存放區的穩定易記名稱。它不是在政策存放區之間轉移、分割或加權授權流量的機制。如果您熟悉在資源版本之間路由流量的功能，例如 Lambda 別名，請注意，政策存放區別名的行為不相同。根據設計，政策存放區別名更接近 AWS KMS 金鑰別名：它為資源提供耐久的名稱，而不是在其前面的路由層。
因此，我們刻意不提供 `UpdatePolicyStoreAlias`操作。若要變更政策存放區別名指向的政策存放區，您可以刪除政策存放區別名，並建立新的政策存放區別名，其名稱相同，並以不同的政策存放區為目標。這不是原子操作，也不保證流量控制機制可以執行。
當您變更政策存放區別名解析的政策存放區時，變更不會同時生效：
+ 更新的映射必須從控制平面傳播到評估授權請求的資料平面。映射不會立即傳播。
+ 由於政策存放區別名解析最終一致且可快取，因此變更後會存在轉換時段。在此時段內，先前關聯的政策存放區會處理一些請求，而新關聯的政策存放區則會處理其他請求。此時段的長度不確定。
在此時段內，您的應用程式可以從任一政策存放區接收授權決策。由於不同的政策存放區可以包含不同的政策、實體和結構描述，因此相同的請求可以根據提供它的政策存放區產生不同的決策。因此，政策存放區別名無法提供政策存放區之間的原子切換，而且它們無法取代部署或流量管理策略。
**請勿使用別名做為切換機制**
請勿建置更高層級infrastructure-as-code或部署基本概念來重新指向政策存放區別名，以便將授權流量從一個政策存放區切換到另一個政策存放區。由於變更不是原子，因此在不確定的期間，請求可以同時針對兩個政策存放區進行授權。這可能會導致不一致的授權決策。若要安全地切換政策存放區，請參閱 [執行非停機時間政策存放區變更](#alias-no-downtime-changes)。
## 執行非停機時間政策存放區變更
由於政策存放區別名不提供原子切換 （請參閱[政策存放區別名不是流量控制機制](#alias-not-traffic-control))，建議您透過重新指向政策存放區別名，避免從一個政策存放區遷移到另一個政策存放區。相反地，請從您的應用程式內控制遷移，以便您可以驗證新的政策存放區，並在需要時立即轉返。下列方法可讓您在不停機的情況下切換政策存放區：
1. 建立新的政策存放區，並為其提供自己的政策存放區別名，讓目前的政策存放區和新的政策存放區各有不同且穩定的名稱。例如，持續`policy-store-alias/example-policy-store`指向您目前的政策存放區`policy-store-alias/example-policy-store-2`，並為新政策存放區建立 。請勿重複使用或重新指向單一政策存放區別名來執行切換。
1. 將政策、結構描述和任何其他組態複寫到新的政策存放區，並與目前的政策存放區平行執行。
1. 將組態值或功能旗標新增至您的應用程式 （例如，使用 AppConfig)，以決定哪些政策存放區別名是授權決策的授權。不要依賴變更別名本身來切換流量。
1. 在陰影模式下執行新的政策存放區。將相同的 `IsAuthorized`或 `IsAuthorizedWithToken`請求傳送至兩個政策存放區，並比較決策。記錄並調查任何差異，直到新的政策存放區傳回您預期的決策為止。
1. 使用 功能旗標逐步將授權決策轉移到新的政策存放區別名，例如，在應用程式主機或使用者區段的分階段推展中。在繼續時監控授權決策和錯誤率。
1. 如果您偵測到問題，請使用功能旗標立即切換回原始政策存放區別名。由於您的應用程式會控制切換，因此回復是即時的，且不依賴別名傳播。
1. 在新的政策存放區經過完整驗證並提供所有流量之後，停用舊政策存放區及其政策存放區別名。
此模式可讓您的應用程式控制每個請求的服務政策存放區，而不是別名傳播。這種控制是讓遷移安全和可逆的原因，它可以避免重新指向政策存放區別名會引入的轉換時段。