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

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

指南主題:

驗證用戶端評估 API 設定

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

  1. 請確認您是如何觸發報表。確認您根據使用的 API 接收正確的報表格式:

    • Attribution Reporting API
    • Private Aggregation API
      • 您可以使用 contributeToHistogram 函式,在 Private Aggregation API 中完成報表。請確認您已傳遞值區塊鍵和值。資料集鍵應為 BigInt 格式。(進一步瞭解 Private Aggregation API)
  2. 如果您按照建議觸發報表,但仍遇到問題,請檢查 Chrome 開發人員控制台的「控制台」和「網路」分頁,看看是否有任何錯誤。

如果您需要針對這些用戶端 API 進一步排解問題,請繼續參閱 Attribution Reporting API 的偵錯指南Private Aggregation API + Shared Storage

排解報表來源設定問題

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

報表來源是否收到報表?

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

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

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

  1. 請確認您是如何觸發報表。確認您根據使用的 API 接收正確的報表格式:

  2. 如果您已按照建議觸發報表,但仍遇到問題,請檢查 Chrome 開發人員工具主控台的「主控台」和「網路」分頁,看看是否有任何錯誤。

如果您需要進一步的疑難排解支援服務,請繼續參閱 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 十六進位格式,然後轉換為位元組陣列。如果您看到的錯誤計數超過一個,請前往 匯總服務 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 說明中的「Aggregation coordinator choice」(匯總協調器選項) 部分範例,定義 `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. 請按照公開雲端服務供應商的程式碼研究室中的步驟,收集偵錯報表,並使用輸出網域金鑰執行匯總服務工作:Google Cloud:請按照 Aggregation Service Google Cloud Codelab 的步驟 3.1.2 至 3.2.3 操作。 b. Amazon Web Services:請按照Aggregation Service AWS Codelab 的步驟 4.2 至 5.3 操作。

如果傳回 SUCCESS 回應,表示轉換運作正常。

可匯總報表是否完整?

請確認匯總報表、輸出網域金鑰和共用資訊皆完整無缺。如需進一步瞭解如何轉換可匯總的報表並建立網域檔案,請參閱範例程式碼

您可能會看到與此問題相關的 API 錯誤,如下所示:

錯誤 INPUT_DATA_READ_FAILED
端點 createJob
檢查 createJob 要求中的 input_data_bucket_nameinput_data_blob_prefixoutput_data_bucket_nameoutput_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 做為酬載。
    • 使用網域檔案執行本機測試工具。如果是 SUCCESS,表示您的 shared_info 檔案遭到竄改。

如果您懷疑有其他錯誤或竄改,請收集 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 執行個體」
  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 問題或提交技術支援表單,通知我們。