雲端 API 本機儲存空間

雲端 API 本機儲存空間可讓您控制將待用訊息資料儲存在哪個位置。如果您的公司屬於受監管的行業（如金融、政府或醫療保健），鑑於監管或公司政策要求，您或會想將自己的待用訊息資料儲存在某個特定國家／地區。

雲端 API 本機儲存空間能提供更多資料管理控制選項，從而為資料增添多一層保護。本機儲存空間功能由雲端 API 運行時環境中的兩個額外限制組成：

使用中資料 TTL（存留時間）：這是一項新加入的資料保留限制，並會強制指定目標管轄範圍以外的 Meta 資料中心雲端 API 可存取處理中訊息內容的時長。使用本機儲存空間時，雲端 API 會在 60 分鐘存留時間後從 Meta 資料中心自動刪除訊息內容。如果使用本機儲存空間，在存留時間過後，目標管轄範圍以外的 Meta 伺服器上不會存留訊息內容。
待用資料位置：這是一項新加入的資料存放限制，並會強制指定允許雲端 API 使用哪個實際位置，作為訊息內容的永久儲存空間。傳入和傳出訊息的文字和影音素材裝載都將儲存在位於指定國家／地區（美國境外）的雲端 API 資料儲存空間中。

為商家電話號碼啟用本機儲存空間設定後，雲端 API 本機儲存空間功能便會使用位於所指定國家／地區的本機化儲存空間（而非其位於美國的預設儲存空間），來存放永久性訊息內容。

本機儲存空間功能與其他雲端 API 私隱和帳戶安全控制選項相輔相成，能讓客戶確保更嚴格地遵守當地資料保護法規。

本機化資料

雲端 API 可為訊息內容執行本機化程序。本機儲存空間功能涵蓋以下訊息流程：

傳出訊息：您透過雲端 API 向收件人傳送的訊息
傳入訊息：您透過雲端 API 收到的訊息

本機儲存空間功能涵蓋以下訊息類型：

文字訊息：文字型裝載（訊息正文）可以本機化
影音素材訊息：影音素材（音訊、文件圖像或影片）裝載可以本機化
範本訊息：含有文字／影音素材裝載的組件可以本機化

此外，本機化資料集亦會包含部分中繼資料屬性集，以便正確地將已加密的本機化訊息裝載配對至最初處理的訊息，並審核本機化的實際情況。儲存的中繼資料會受到標記化和加密技術所保護。

雲端 API 本機儲存空間功能旨在讓您的商家透過雲端 API 設定，直接控制您敏感待用資料的儲存位置，同時讓您可以靈活地選擇將資料存放在全域哪個位置。

適用地區

《Meta 雲端 API 代管條款》列明可使用雲端 API 本機儲存空間功能的地區。您可以在註冊手機號碼時設定的 data_localization_region 參數下，找到本機儲存空間功能目前適用的地區。

要求

只能針對尚未註冊的商家電話號碼啟用或停用本機儲存空間功能。

限制

如果使用啟用了本機儲存空間設定的手機號碼上載影音素材檔案，這些檔案只能透過該特定手機號碼存取，並且不能與同一商家關聯的其他手機號碼分享。

啟用本機儲存空間

使用 API 21.0 或更新版本並按照以下步驟，為未註冊的商家電話號碼啟用本機儲存空間。如果使用的是較早版本的 API，請參閱啟用本機儲存空間（v20 及較早版本）。

步驟 1：為號碼啟用本機儲存空間

使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings 端點在未註冊的商家電話號碼上啟用本機儲存空間：

要求語法

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED", 
    "data_localization_region": "<COUNTRY_CODE>"
  }
}

將 <COUNTRY_CODE> 設定為應儲存待用資料的國家／地區的國碼／區碼。

回應語法

{
  "success": <SUCCESS>
}

成功的話，<SUCCESS> 將設定為 true。

要求範例

curl 'https://graph.facebook.com/v21.0/106540352242922/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED", 
    "data_localization_region": "BR"
  }
}'

回應範例

{
  "success": true
}

步驟 2：註冊號碼

使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register 端點註冊商家電話號碼。

要求語法

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register

{
  "messaging_product": "whatsapp",
  "pin": "<TWO_STEP_PIN>"
}

將 <TWO_STEP_PIN> 設定為商家電話號碼所需的雙重認證 PIN。

回應語法

{
  "success": <SUCCESS>
}

成功的話，<SUCCESS> 將設定為 true。

要求範例

curl 'https://graph.facebook.com/v21.0/v21.0/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "123456"
}'

回應範例

{
  "success": true
}

獲取本機儲存空間設定

使用 GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings 端點在 WhatsApp Business 電話號碼上獲取本機儲存空間設定。例如：

curl 'https://graph.facebook.com/v21.0/179776755229976/settings' \
-H 'Authorization: Bearer EAAJB...'

這會在商家電話號碼上傳回代表本機儲存空間設定的節點。例如：

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED",
    "data_localization_region": "BR"
  }
}

停用本機儲存空間

使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings 端點和 API 21.0 或更新版本，在未註冊的商家電話號碼上停用本機儲存空間。如果使用的是較早版本的 API，請參閱停用本機儲存空間（v20 及較早版本）。

要求語法

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/>settings

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_DISABLED"
  }
}

將 <COUNTRY_CODE> 設定為應儲存待用資料的國家／地區的國碼／區碼。

回應語法

{
  "success": <SUCCESS>
}

成功的話，<SUCCESS> 將設定為 true。

要求範例

curl 'https://graph.facebook.com/v21.0/106540352242922/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_DISABLED"
  }
}'

回應範例

{
  "success": true
}

啟用本機儲存空間（v20 及較早版本）

若要使用 API 20.0 或較早版本為未註冊的商家電話號碼啟用本機儲存空間，請按照下列步驟操作：

步驟 1：檢查驗證狀態

使用 GET /<WHATSAPP_BUSINESS_PHONE_NUMBER> 端點並要求 code_verification_status 欄位。如果代碼驗證狀態為 VERIFIED，請跳到步驟 4。否則，執行步驟 2。

步驟 2：要求驗證碼

使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/request_code 端點要求驗證碼。成功的話，API 會以 true 回覆，並且驗證碼會透過您在 code_method 參數中指定的方法傳送至商家電話號碼。

例如，此查詢要求透過短訊並採用英文（美國地區）傳送驗證碼。

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

在下一步中使用已送達短訊裡的驗證碼。

步驟 3：驗證商家電話號碼

使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/verify_code 端點和上一步收到的短訊驗證碼，來驗證商家電話號碼。

例如：

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/verify_code?code=123830' \
-H 'Authorization: Bearer EAAJB...'

步驟 4：重新註冊商家電話號碼

使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register 端點註冊商家電話號碼。使用 data_localization_region 參數來表示待用資料應儲存在哪個國家／地區。

例如，此要求會在商家電話號碼上啟用本機儲存空間，並將應儲存資料的國家／地區設為印度：

curl 'https://graph.facebook.com/v21.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "123456",
  "data_localization_region": "IN"
}'

停用本機儲存空間（v20 及較早版本）

使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/deregister 端點和 API 20.0 或較早版本，在商家電話號碼上停用本機儲存空間。

例如：

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/deregister' \
-H 'Authorization: Bearer EAAJB...'

請注意，此操作將取消註冊商家電話號碼，使其無法用於 WhatsApp 雲端 API。如想繼續配合雲端 API 使用商家電話號碼，但無需啟用本機儲存空間，您必須在不提供 data_localization_region 參數的情況下重新註冊該號碼。

常見問題

問：將手機號碼轉移至設有本機儲存空間功能的雲端 API 版本時，有哪些轉移路徑？

我們支援透過任何路徑以轉移至設有本機儲存空間功能的雲端 API 版本，這些路徑包括：

將現有內部部署 API 手機號碼轉移至設有本機儲存空間功能的雲端 API 版本
將現有雲端 API 手機號碼轉移至設有本機儲存空間功能的雲端 API 版本
使用新雲端 API 手機號碼來啟用本機儲存空間功能

在所有上述情況下，您都需要為所選手機號碼向 /register 端點傳送 POST 要求，並在要求中使用新參數 data_localization_region 來指定將資料本機化的目標國家／地區。

問：轉移程序是否有風險？這個過程是否會造成停機？

轉移程序並沒有任何風險，其過程與從內部部署 API 轉移至雲端 API 類似。請參閱此處的開發人員文件。停機時間通常少於 5 分鐘，且您無需重新驗證商家電話號碼。