診斷環境 (新環境或升級環境)

使用匯總服務時，可能會因為多種因素而發生問題，包括報表格式、輸出網域問題和協調器問題。瞭解錯誤來源和其中包含的任何中繼資料，有助於準確診斷問題。

指南主題：

確認用戶端評估 API 設定

確認來源伺服器已正確註冊後，請完成下列步驟：

  1. 請檢查您觸發報表的方式。確認您收到的報表格式正確無誤，符合所用 API 的規定：

    • Attribution Reporting API
    • Private Aggregation API
      • 您可以使用 contributeToHistogram 函式，在 Private Aggregation API 中完成報表作業。確認您傳遞的是 bucket 鍵和值。儲存空間金鑰的格式應為 BigInt。(進一步瞭解 Private Aggregation API)

  2. 如果您是按照建議觸發報表，但問題仍未解決，請檢查「Console」和「Network」分頁中的 Chrome 開發人員控制台是否出現錯誤。

如需這些用戶端 API 的進一步疑難排解支援，請繼續參閱 Attribution Reporting API 的偵錯指南，以及 Private Aggregation API + Shared Storage。

排解報表來源設定問題

報表來源伺服器是您宣告正確對應 .well-known 端點的位置，可匯總報表會傳送至該端點。確認您部署的報表來源伺服器已正確註冊。

您的報表來源是否收到報表？

確認您部署的報表來源伺服器已正確註冊。您已在這個伺服器中宣告正確的對應 .well-known 端點，可匯總的報表會傳送至這些端點。

用戶端評估 API 相符的可匯總端點
Attribution Reporting POST /.well-known/attribution-reporting/report-aggregate-attribution
私密匯總 + 共用儲存空間 (組合) POST /.well-known/private-aggregation/report-shared-storage
Private Aggregation + Protected Audience (Combo) POST /.well-known/private-aggregation/report-protected-audience

確認原始伺服器已正確註冊後，請完成下列步驟：

  1. 請檢查您觸發報表的方式。確認您收到的報表格式正確無誤，符合所用 API 的規定：

  2. 如果您按照建議觸發報表，但問題仍未解決，請檢查「Console」和「Network」分頁中的 Chrome 開發人員控制台是否出現錯誤。

如需這些用戶端 API 的進一步疑難排解支援，請參閱 Attribution Reporting API 的偵錯指南，以及 Private Aggregation API + Shared Storage。

排解匯總報表問題

用戶端評估 API 會產生匯總報表，並傳送至您的報表來源。這些報表應由您的報表端點轉換為 AVRO 格式。如果這項轉換有問題，或是報表本身不完整，您可能會在匯總服務中看到錯誤。

可匯總報表是否正確轉換？

確認您的報表端點 (.well-known/…) 能正確將指定的匯總 JSON 報表轉換為 AVRO。

這個問題會導致下列 API 錯誤：

錯誤 DECRYPTION_ERROR
範例 
                "result_info": {
                    "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                    "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                    "error_summary": {
                        "error_counts": [
                            {
                                "category": "DECRYPTION_ERROR",
                                "count": 1,
                                "description": "Unable to decrypt the report. This may be caused by: tampered aggregatable report shared info, corrupt encrypted report, or other such issues."
                            },
                            {
                                "category": "NUM_REPORTS_WITH_ERRORS",
                                "count": 1,
                                "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                            }
                        ],
                        "error_messages": []
                    }
                }
檢查 這可能是因為解密錯誤所致，而解密錯誤可能是因為系統未正確產生 AVRO 報表 (無論是可匯總的 AVRO 報表或輸出網域 AVRO)，可匯總的 AVRO 報表是否正確產生？酬載必須經過 base64 解碼，並轉換為位元組陣列。確認報表為 avro 格式。此外，請檢查輸出網域 AVRO 是否正確。儲存區會轉換為逸出 Unicode 十六進位格式，然後轉換為位元組陣列。 如果看到多個錯誤計數，請前往 Aggregation Service GitHub 頁面，進一步瞭解錯誤。
錯誤 DECRYPTION_KEY_NOT_FOUND
範例 
                "result_info": {
                    "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                    "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                    "error_summary": {
                        "error_counts": [{
                            "category": "DECRYPTION_KEY_NOT_FOUND",
                            "count": 1,
                            "description": "Could not find decryption key on private key endpoint."
                        }, {
                            "category": "NUM_REPORTS_WITH_ERRORS",
                            "count": 1,
                            "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                        }],
                        "error_messages": []
                    }
                }
檢查 Attribution Reporting API

如果是 Attribution Reporting API，這項錯誤可能是由觸發登錄問題所導致。確認他們已使用 aggregation_coordinator_origin 欄位，向正確的雲端註冊觸發條件 (請參閱這篇文章)。您也可能將 AWS 加密報表提供給 Google Cloud 部署的匯總服務，或將 Google Cloud 加密報表提供給 AWS 部署的匯總服務。請他們驗證用於加密可匯總報表的公開金鑰端點。如果是 Google Cloud，可匯總報表中的 `aggregation_coordinator_origin` 欄位應為 https://publickeyservice.msmt.gcp.privacysandboxservices.com。如果是 AWS，則應為 https://publickeyservice.msmt.aws.privacysandboxservices.com。

Private Aggregation API

如果是 Private Aggregation API，您必須使用 Private Aggregation API 說明文件「匯總協調器選擇」一節中的範例，定義 `aggregationCoordinatorOrigin`。請將 https://publickeyservice.msmt.gcp.privacysandboxservices.com 指定為 aggregationCoordinatorOrigin。

例如：

                sharedStorage.run('someOperation', {'privateAggregationConfig':
                {'aggregationCoordinatorOrigin': ' https://publickeyservice.msmt.gcp.privacysandboxservices.com'}});
錯誤 DECRYPTION_KEY_FETCH_ERROR
範例 
                "result_info": {
                        "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                        "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                        "error_summary": {
                            "error_counts": [
                                {
                                    "category": "DECRYPTION_KEY_FETCH_ERROR",
                                    "count": 1,
                                    "description": "Fetching the decryption key for report decryption failed. This can happen using an unapproved aggregation service binary, running the aggregation service binary in debug mode, key corruption or service availability issues."
                                },
                                {
                                    "category": "NUM_REPORTS_WITH_ERRORS",
                                    "count": 1,
                                    "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                                }
                            ]
                        }
                }
檢查 如果二進位檔未獲核准或有偵錯模式問題，使用正確的二進位檔即可修正問題。請按照這裡的說明使用預先建構的 AMI，或自行建構 AMI。

請完成下列步驟進行驗證：

  1. 您可以使用 aggregatable_report_converter 工具，將從 .well-known 端點收集的可匯總報表轉換為 AVRO，並建立輸出網域金鑰。(注意：輸出網域檔案應為 16 位元組的大端位元組字串)。

  2. 請按照公開雲端服務供應商的程式碼研究室步驟，收集偵錯報表，並使用輸出網域金鑰執行匯總服務工作： a. Google Cloud：請按照「匯總服務 Google Cloud 程式碼研究室」的步驟 3.1.2 至 3.2.3 操作。 b. Amazon Web Services：請按照匯總服務 AWS Codelab 的步驟 4.2 至 5.3 操作。

如果傳回 SUCCESS 回應，表示轉換追蹤功能正常運作。

可匯總報表是否完好無缺？

確認匯總報表、輸出網域金鑰和共用資訊完好無損。如需更多資訊，請參閱範例程式碼，瞭解如何轉換可匯總的報表及建立網域檔案。

您可能會看到下列 API 錯誤，這些錯誤與這個問題相關：

錯誤 INPUT_DATA_READ_FAILED
端點 createJob
檢查 createJob 要求中的 input_data_bucket_name、input_data_blob_prefix、output_data_bucket_name 和 output_data_blob_prefix 欄位是否正確？輸入報表資料位置是否包含要處理的報表？您是否具備從報表和輸出網域的儲存位置讀取資料的權限？

請完成下列步驟進行驗證：

  1. 驗證匯總報表：

    • 產生匯總報表，並使用 aggregatable_report_converter 工具將輸出網域轉換為 AVRO 格式。
    • 使用這份可匯總的報表和輸出網域檔案，執行 createJob 要求。
    • 如果傳回 SUCCESS，表示可匯總報表完好無缺。如果傳回錯誤，表示您有可匯總報表的問題，或是報表和網域都有問題。
    • 請繼續下一個步驟，檢查網域檔案。

  2. 驗證輸出網域檔案：

    • 產生輸出網域檔案，並使用 aggregatable_report_converter 工具建立可匯總報表。
    • 使用這份可匯總的報表和輸出網域檔案，執行 createJob 要求。
    • 如果傳回 SUCCESS，表示輸出網域完好無損，但您的程式碼有問題，導致無法建立可匯總的報表。
    • 請繼續執行下一個步驟，檢查 shared_info。

  3. 驗證分享的資訊：

    • 確認您已啟用偵錯報表。啟用偵錯功能的報表會提供 debug_cleartext_payload 欄位。
    • 建立偵錯報表，以搭配本機測試工具使用，並使用 debug_cleartext_payload 做為酬載。
    • 使用網域檔案執行本機測試工具。如果是這樣，表示 shared_info 檔案遭到竄改。SUCCESS

如果懷疑有其他錯誤或竄改行為，請收集 JSON 匯總報表、網域金鑰、產生的匯總 AVRO 報表和輸出網域，然後繼續進行後續步驟。

檢查新的部署版本

確認您使用的匯總服務版本是否仍受支援。確認您使用的版本後，請查看匯總服務版本清單，確認您的版本沒有支援終止警告：This release has reached its end of support on { date }。下列操作說明適用於支援的公有雲，可協助您判斷已部署的版本。

Google Cloud 的步驟

  1. 前往「Compute Engine」>「VM 執行個體」。
  2. 按一下名稱中含有 -worker- 的虛擬機器執行個體。
  3. 找到 Custom Metadata 部分，然後找出 tee-image-reference 鍵。
  4. tee-image-reference 的值會包含版本號碼。舉例來說，以下路徑的版本號碼為 v2.9.1。這些是預先建構的映像檔，位於 Google Cloud 專案的 Artifact Registry 中。
    • 注意：如果您使用預先建構的素材資源，這項資訊就非常重要。如果您未使用，則這項資訊應與您個人命名及標記圖片的資訊相符。(例如：us.docker.pkg.dev/<gcp_project_name>/artifacts:aggregation-service- container-artifacts-worker_mp_go_prod:2.9.1)

Amazon Web Services 的操作步驟

  1. 在 Amazon Web Services 控制台中，前往「EC2 Instances」。
  2. 按一下名稱為 aggregation-service-operator-dev-env 的執行個體。
  3. 在執行個體頁面中，依序找到「詳細資料」>「AMI (Amazon Machine Image)」
  4. 圖片路徑中應包含版本名稱。舉例來說，下列路徑的版本號碼為 v2.9.1。
    • 注意：如果您使用預先建構的素材資源，這項資訊就非常重要。如果您未使用，則這項資訊應與您個人命名及標記圖片的資訊相符。(例如：aggregation-service-enclave_2.9.1--2024-10-03T01-24-25Z)

後續步驟

如果找不到解決方案，請提交 GitHub 問題或填寫技術支援表單，通知我們。