為評估結果加上註解

在 Google Cloud Fraud Defense 中，您可以為評估作業加上註解，提供有關評估準確度和使用者合法性的基準真相意見回饋。將互動結果和驗證詳細資料提交回 Fraud Defense，有助於調整網站專屬模型，並逐步提升偵測成效。

為評估結果加上註解的時機

Fraud Defense 會在建立評估作業時提供分數，協助您瞭解使用者互動的風險等級。之後，當網站有更多使用者互動資訊，可判斷互動是否正當或涉及詐欺時，您就能確認或更正 reCAPTCHA 的評估結果。方法是將 reCAPTCHA 評估 ID 傳回 Google，並標示為 LEGITIMATE 或 FRAUDULENT。確認或修正 reCAPTCHA 的評估結果，可提升網站的 Fraud Defense 成效。

如要提升 Fraud Defense 的效能，除了潛在評估錯誤的註解外，您也可以確認真陽性和真陰性的註解。舉例來說，如果使用者成功使用雙重驗證方法完成驗證，並獲得高 reCAPTCHA 分數，您可以將評估結果加上 LEGITIMATE 註解。或者，如果 Google Cloud Fraud Defense 分數偏低，且網站判定互動屬於詐欺或濫用行為，您可以將評估結果標註為 FRAUDULENT。

以下列出一些使用者互動範例的額外資訊，說明如何判斷使用者互動是否正當或詐欺：

• 信用卡交易退單或其他具體詐欺證據，顯示先前的財務交易有詐欺行為。
• 如果新帳戶傳送的訊息遭其他使用者標示為垃圾訊息，可能表示該帳戶是透過詐欺方式建立。
• 如果使用者無法登入帳戶，並因此提交客服案件，可能表示登入嘗試是合法的。
• 如果使用者在採用 Fraud Defense 防範抓取行為的網站上購物或預訂，可能表示使用者是合法的。

事前準備

• 確認您具備下列 Identity and Access Management 角色：reCAPTCHA Enterprise 代理人 (roles/recaptchaenterprise.agent)。

• 視您設定 Fraud Defense 的位置而定，請完成適當的步驟：

  • 為網站建立評估。
  • 為行動應用程式建立評估作業。
  • 設定 WAF 整合。

擷取評估 ID

如要為評估作業加註，請透過下列方式擷取專屬評估作業 ID：

• 如果是網頁和行動整合，您可以從評估回應中擷取專屬評估 ID。

  建立評估後，您會收到 JSON 回應，如以下範例所示。

  從 JSON 回應的 name 欄位擷取專屬評估 ID。

  {
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
  },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
  "event": {
    "token": "RESPONSE_TOKEN",
    "siteKey": "KEY_ID"
  },
  "name": "ASSESSMENT_ID"
  }

• 如果是 WAF 整合，您可以從 reCAPTCHA 權杖擷取專屬評估 ID。專屬評估 ID 是由 16 個英數字元組成的專屬字串，顯示在 reCAPTCHA 權杖結尾的 :U= 後方。舉例來說，如果 reCAPTCHA 權杖是 .................U=6ZZZZe73fZZZZZZ0，則評估 ID 為 6ZZZZe73fZZZZZZ0。

為評估結果加上註解

1. 視用途而定，決定要在要求 JSON 主體中新增的資訊和標籤。

   下表列出可用來加註事件的標籤和值：

   標籤	說明	要求範例
   reasons	選用。可協助您評估的標籤。 請在事件發生後幾秒或幾分鐘內，在 reasons 標籤中提供即時事件詳細資料，因為這些資料會影響即時偵測。 如需可能的值清單，請參閱原因值。 範例：如要偵測帳戶入侵，請使用 CORRECT_PASSWORD 或 INCORRECT_PASSWORD 值，標註輸入的密碼是否正確。如果您已部署自己的多重驗證，可以新增下列值：INITIATED_TWO_FACTOR、PASSED_TWO_FACTOR 或 FAILED_TWO_FACTOR。	{ "reasons": ["INCORRECT_PASSWORD"] }
   annotation	選用。表示評估合法性的標籤。 提供登入和註冊事件的相關事實，驗證或修正 annotation 標籤中的風險評估。 可能的值：LEGITIMATE 或 FRAUDULENT。 您可以隨時傳送這項資訊，也可以在批次工作中傳送。 不過，我們建議您在事件發生後幾秒或幾分鐘內傳送這項資訊，因為這會影響即時偵測。	{ "annotation": "LEGITIMATE" }

2. 使用 gcloud CLI 或 API 金鑰，透過 projects.assessments.annotate 方法為評估作業加上註解。

   注意：如果您使用的是 v1beta1 版 API，建議改用 v1 版，因為 Account Defense 等新功能僅適用於 v1 版。如要從 v1beta1 遷移至 v1，請參閱「從 v1beta API 遷移至 v1 API」。

   gcloud CLI

   使用任何要求資料之前，請先修改下列項目的值：

   • ASSESSMENT_ID：projects.assessments.create 呼叫傳回的 name 欄位值。
   • ANNOTATION_LABEL：這個標籤會指出評估結果是否為正當或詐欺行為。可能的值為 LEGITIMATE 或 FRAUDULENT。
   • ANNOTATION_REASON：說明為這項評估選擇的註解情境。如要瞭解可能的值，請參閱為評估作業加上註解的原因。

   HTTP 方法和網址：

   POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

   JSON 要求內文：

   {
   "annotation": "ANNOTATION_LABEL"
   "reasons": "ANNOTATION_REASON"
   }
   

   如要傳送要求，請選擇以下其中一個選項：

   curl

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"

   PowerShell

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

   您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

   API 金鑰

   使用任何要求資料之前，請先修改下列項目的值：

   • ASSESSMENT_ID：projects.assessments.create 呼叫傳回的 name 欄位值
   • ANNOTATION_LABEL：這個標籤會指出評估結果是否為正當或詐欺行為。可能的值為 LEGITIMATE 或 FRAUDULENT。
   • ANNOTATION_REASON：說明為這項評估選擇的註解情境。如要瞭解可能的值，請參閱為評估作業加上註解的原因。

   HTTP 方法和網址：

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY

   JSON 要求內文：

   {
   "annotation": "ANNOTATION_LABEL"
   "reasons": "ANNOTATION_REASON"
   }
   

   如要傳送要求，請選擇以下其中一個選項：

   curl

   注意：請建立 API 金鑰，以便向 API 進行驗證。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY"

   PowerShell

   注意：請建立 API 金鑰，以便向 API 進行驗證。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $headers = @{  }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY" | Select-Object -Expand Content

   您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

後續步驟

• 瞭解 Fraud Defense 的使用者帳戶保護功能。