為評估結果加上註解

本頁說明如何針對 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 防範資料擷取的網站上購物或預訂，可能表示使用者是合法的。

事前準備

• 請確認您具備下列身分與存取權管理角色： 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': u'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 值，為輸入的密碼是否正確加上註解。如果您部署了自己的 MFA，可以新增下列值：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 版本，因為只有 v1 版本提供 Account Defense 等新功能。如要從 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 的使用者帳戶保護功能。