오프라인 데이터 진단 모니터링
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Google Ads API를 사용하여 전환 가져오기 및 조정 프로세스의 전반적인 상태에 관한 정보가 포함된 오프라인 데이터 진단을 가져옵니다.
계정의 최신 오프라인 데이터 진단을 가져오려면 다음 리소스 중 하나를 사용하세요.
계정 수준 진단
계정 수준 전환 업로드 진단을 가져오려면 다음 GAQL 쿼리를 사용하세요.
SELECT
customer.id,
offline_conversion_upload_client_summary.alerts,
offline_conversion_upload_client_summary.client,
offline_conversion_upload_client_summary.daily_summaries,
offline_conversion_upload_client_summary.job_summaries,
offline_conversion_upload_client_summary.last_upload_date_time,
offline_conversion_upload_client_summary.pending_event_count,
offline_conversion_upload_client_summary.pending_rate,
offline_conversion_upload_client_summary.status,
offline_conversion_upload_client_summary.success_rate,
offline_conversion_upload_client_summary.successful_event_count,
offline_conversion_upload_client_summary.total_event_count
FROM offline_conversion_upload_client_summary
이 쿼리는 최근 가져오기에 사용된 각 클라이언트 유형에 대해 별도의 OfflineConversionUploadClientSummary 행을 반환합니다. 예를 들어 Google Ads API와 Google Ads UI를 모두 사용하여 최근에 가져온 경우 결과에는 GOOGLE_ADS_API 및 GOOGLE_ADS_WEB_CLIENT의 client 값이 별도의 항목으로 포함됩니다.
전환 액션 수준 진단
전환 액션 수준에서 전환 업로드 진단을 가져오려면 다음 GAQL 쿼리를 사용하세요.
SELECT
offline_conversion_upload_conversion_action_summary.conversion_action_name,
offline_conversion_upload_conversion_action_summary.alerts,
offline_conversion_upload_conversion_action_summary.client,
offline_conversion_upload_conversion_action_summary.daily_summaries,
offline_conversion_upload_conversion_action_summary.job_summaries,
offline_conversion_upload_conversion_action_summary.last_upload_date_time,
offline_conversion_upload_conversion_action_summary.pending_event_count,
offline_conversion_upload_conversion_action_summary.status,
offline_conversion_upload_conversion_action_summary.successful_event_count,
offline_conversion_upload_conversion_action_summary.total_event_count
FROM offline_conversion_upload_conversion_action_summary
WHERE offline_conversion_upload_conversion_action_summary.conversion_action_id = < INSERT CONVERSION ACTION ID >
계정 수준 진단과 마찬가지로 이 쿼리는 최근 가져오기에 사용된 각 클라이언트 유형에 대해 별도의 OfflineConversionUploadConversionActionSummary 행을 반환합니다. 예를 들어 Google Ads API와 Google Ads UI를 모두 사용하여 최근에 가져온 경우 결과에는 GOOGLE_ADS_API 및 GOOGLE_ADS_WEB_CLIENT의 client 값이 별도의 항목으로 포함됩니다.
요약 해석 방법
각 OfflineConversionUploadClientSummary 또는 OfflineConversionUploadConversionActionSummary에는 client의 가져오기의 전반적인 상태를 반영하는 status 필드가 있습니다. 또한 다음 정보가 포함됩니다.
- 수신된 총 이벤트 수입니다.
- 성공적으로 처리된 이벤트의 수입니다.
- 대기 중인 이벤트 (아직 처리 중인 이벤트)의 수입니다.
OfflineConversionError로 그룹화된 오류 요약을 제공하는 alerts 필드
이러한 필드에는 가져오기의 가장 최근 전체 캘린더 날짜의 정보가 포함됩니다. 이 정보를 사용하여 가져오기의 현재 상태를 평가합니다.
또한 각 OfflineConversionUploadClientSummary 또는 OfflineConversionUploadConversionActionSummary에는 다음과 같은 두 가지 유형의 보고서가 포함됩니다.
daily_summaries- 지난 7일 동안의 가져오기 요청의
successful_count, failed_count, pending_count이며 가져오기 date로 그룹화됩니다.
job_summaries가장 최근 7개 가져오기 요청의 successful_count, failed_count, pending_count입니다. job_id로 그룹화됩니다. job_id는 UploadClickConversionsRequest 및 UploadConversionAdjustmentsRequest의 선택적 필드입니다. job_id을 2^31보다 작은 음수가 아닌 숫자로 설정하거나 Google Ads API가 시스템 생성 작업 ID를 요청에 할당하도록 할 수 있습니다. 어떤 옵션을 선택하든 UploadClickConversionsResponse 또는 UploadConversionAdjustmentsResponse는 job_id를 반환합니다.
자체 job_id를 할당하는 것이 유용한 한 가지 시나리오는 여러 요청을 사용하여 많은 수의 전환을 가져오는 단일 작업 또는 프로세스가 있는 경우입니다. 이러한 각 요청에서 job_id을 동일한 값으로 설정하면 job_summaries에서 작업의 단일 항목을 검색할 수 있습니다. 대신 Google Ads API가 각 요청의 job_id에 시스템 생성 값을 할당하도록 하면 job_summaries에 각 요청에 대한 별도의 항목이 포함되어 작업의 전반적인 상태를 분석하기가 더 어려워질 수 있습니다.
요약 사용 방법
가져오기 프로세스에서 전환과 개선사항이 예상대로 기록되도록 하려면 각 계정의 요약을 주기적으로 가져오세요. 요약의 status이 EXCELLENT이 아닌 경우 alerts 아래의 오류 목록을 사용하여 가져오기 프로세스를 수정하여 이러한 오류를 줄이거나 없애세요.
예를 들면 다음과 같습니다.
상태가 NEEDS_ATTENTION이면 가져오기 작업의 상당 부분이 실패한 것입니다. alerts 아래의 오류를 검토하고 가져오기 프로세스를 수정하여 이러한 오류를 줄이거나 없앱니다.
상태가 NO_RECENT_UPLOADS이면 Google Ads에서 client에 대한 최근 가져오기를 수신하지 않은 것입니다. 예상치 못한 경우 해당 클라이언트를 사용하여 가져오기를 실행하는 프로세스를 검토하세요.
예를 들어 GOOGLE_ADS_API의 status가 NO_RECENT_UPLOADS인 경우 Google Ads API를 사용하는 가져오기 프로세스가 최근에 중지되었음을 나타낼 수 있습니다.
처리되지 않은 이벤트가 많이 전송된 특정 가져오기 날짜 또는 작업이 있었는지 확인하려면 daily_summaries 및 job_summaries의 successful_count, failed_count, pending_count를 확인하세요.
대기 상태의 이벤트는 완료하는 데 최대 24시간이 걸릴 수 있습니다.
오프라인 데이터 진단을 개선하는 방법에 대한 자세한 내용은 고객센터를 참고하세요.
제한사항
가져오기 요약을 검색할 때는 다음 사항에 유의하세요.
Google Ads API는 searchStream 또는 search 요청의 customer_id이 최근에 전환을 가져오는 데 사용한 고객과 동일한 경우에만 오프라인 데이터 진단을 반환합니다.
예를 들어 교차 계정 전환 추적을 사용하는 고객 계정에는 진단이 포함되지 않을 수 있습니다. 하지만 가져오기에 사용하는 관리자 계정의 customer_id와 일치하는 customer_id를 사용하여 요청을 전송하여 진단을 가져올 수 있습니다.
Google Ads에서는 리드 확보용 향상된 전환 가져오기에서 발생하는 CLICK_NOT_FOUND 오류를 경고로 처리합니다. 따라서 alerts에 이 오류에 대한 항목이 포함된 경우 해당 작업은 여전히 성공한 것으로 간주되며 successful_event_count에 포함됩니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-26(UTC)
[null,null,["최종 업데이트: 2025-08-26(UTC)"],[[["\u003cp\u003eThe Google Ads API allows retrieval of offline data diagnostics, offering insights into the health of your conversion uploads and adjustments.\u003c/p\u003e\n"],["\u003cp\u003eYou can access these diagnostics at both the account level and the conversion action level using specific GAQL queries.\u003c/p\u003e\n"],["\u003cp\u003eDiagnostics encompass data like total events, successful events, pending events, and alerts on errors, helping assess the upload process.\u003c/p\u003e\n"],["\u003cp\u003eDaily and job summaries are included, offering a detailed view of upload request performance over the past 7 days.\u003c/p\u003e\n"],["\u003cp\u003eRegularly review these summaries to ensure smooth conversion tracking, addressing any alerts to optimize the upload process for better results.\u003c/p\u003e\n"]]],[],null,["# Monitor offline data diagnostics\n\n| **Note:** For enhanced conversions for leads imports, use the [enhanced conversions for leads diagnostics report](//support.google.com/google-ads/answer/15249267) in the Google Ads UI to monitor your import health.\n\nUse the Google Ads API to retrieve\n[offline data diagnostics](//support.google.com/google-ads/answer/13812240),\nwhich contain information about the overall health of your conversion import and\nadjustment processes.\n\nTo retrieve the latest offline data diagnostics for your account, use\none of the following resources:\n\n- [`offline_conversion_upload_client_summary`](/google-ads/api/fields/v21/offline_conversion_upload_client_summary) aggregates import diagnostics at the account level.\n- [`offline_conversion_upload_conversion_action_summary`](/google-ads/api/fields/v21/offline_conversion_upload_conversion_action_summary) aggregates import diagnostics at the conversion action level.\n\nAccount level diagnostics\n-------------------------\n\nTo retrieve account level conversion upload diagnostics, use the following\nGAQL query: \n\n SELECT\n customer.id,\n offline_conversion_upload_client_summary.alerts,\n offline_conversion_upload_client_summary.client,\n offline_conversion_upload_client_summary.daily_summaries,\n offline_conversion_upload_client_summary.job_summaries,\n offline_conversion_upload_client_summary.last_upload_date_time,\n offline_conversion_upload_client_summary.pending_event_count,\n offline_conversion_upload_client_summary.pending_rate,\n offline_conversion_upload_client_summary.status,\n offline_conversion_upload_client_summary.success_rate,\n offline_conversion_upload_client_summary.successful_event_count,\n offline_conversion_upload_client_summary.total_event_count\n FROM offline_conversion_upload_client_summary\n\nThis query returns separate\n[`OfflineConversionUploadClientSummary`](/google-ads/api/reference/rpc/v21/OfflineConversionUploadClientSummary)\nrows for each type of client used in recent imports. For example, if you\nrecently imported using both the Google Ads API and the Google Ads UI, the results\ncontain separate entries for the `client` values of `GOOGLE_ADS_API` and\n`GOOGLE_ADS_WEB_CLIENT`.\n\nConversion action level diagnostics\n-----------------------------------\n\nTo retrieve conversion upload diagnostics at the conversion action level, use\nthe following GAQL query: \n\n SELECT\n offline_conversion_upload_conversion_action_summary.conversion_action_name,\n offline_conversion_upload_conversion_action_summary.alerts,\n offline_conversion_upload_conversion_action_summary.client,\n offline_conversion_upload_conversion_action_summary.daily_summaries,\n offline_conversion_upload_conversion_action_summary.job_summaries,\n offline_conversion_upload_conversion_action_summary.last_upload_date_time,\n offline_conversion_upload_conversion_action_summary.pending_event_count,\n offline_conversion_upload_conversion_action_summary.status,\n offline_conversion_upload_conversion_action_summary.successful_event_count,\n offline_conversion_upload_conversion_action_summary.total_event_count\n FROM offline_conversion_upload_conversion_action_summary\n WHERE offline_conversion_upload_conversion_action_summary.conversion_action_id = \u003c INSERT CONVERSION ACTION ID \u003e\n\nSimilar to account level diagnostics, this query returns separate\n[`OfflineConversionUploadConversionActionSummary`](/google-ads/api/reference/rpc/v21/OfflineConversionUploadConversionActionSummary)\nrows for each type of client used in recent imports. For example, if you\nrecently imported using both the Google Ads API and the Google Ads UI, the results\ncontain separate entries for the `client` values of `GOOGLE_ADS_API` and\n`GOOGLE_ADS_WEB_CLIENT`.\n\nHow to interpret these summaries\n--------------------------------\n\nEach `OfflineConversionUploadClientSummary` or\n`OfflineConversionUploadConversionActionSummary` has a `status` field, that\nreflects the [overall health](//support.google.com/google-ads/answer/13812240#2)\nof imports for the `client`. It also contains the following information:\n\n- The count of total events received.\n- The count of successfully processed events.\n- The count of pending events (events that are still being processed).\n- An `alerts` field, that provides a summary of errors, grouped by [`OfflineConversionError`](/google-ads/api/reference/rpc/v21/OfflineConversionError).\n\nAll of these fields contain information from the most recent full calendar day\nof imports. Use this information to assess the *current* health of your imports.\n\nIn addition, each `OfflineConversionUploadClientSummary` or\n`OfflineConversionUploadConversionActionSummary` contains two different\ntypes of reports:\n\n`daily_summaries`\n: A `successful_count`, `failed_count`, and `pending_count` of import requests\n from the last 7 days, grouped by import `date`.\n\n`job_summaries`\n\n: The `successful_count`, `failed_count`, and `pending_count` of the 7 most\n recent import requests, grouped by `job_id`. The `job_id` is an optional field\n of [`UploadClickConversionsRequest`](/google-ads/api/reference/rpc/v21/UploadClickConversionsRequest) and\n [`UploadConversionAdjustmentsRequest`](/google-ads/api/reference/rpc/v21/UploadConversionAdjustmentsRequest). You can either set the\n `job_id` to a non-negative number less than `2^31` or let the Google Ads API assign a\n system-generated job ID to your request. Regardless of which option you\n choose, the [`UploadClickConversionsResponse`](/google-ads/api/reference/rpc/v21/UploadClickConversionsResponse) or\n [`UploadConversionAdjustmentsResponse`](/google-ads/api/reference/rpc/v21/UploadConversionAdjustmentsResponse) returns the `job_id`.\n\n One scenario where assigning your own `job_id` is useful is when you have a\n single job or process that imports a large number of conversions using\n multiple requests. If you set the `job_id` on each of those requests to the\n same value, then you can retrieve a single entry for the job from\n `job_summaries`. If instead you let the Google Ads API assign a system-generated\n value to the `job_id` of each request, the `job_summaries` contains a separate\n entry for each request, which could make analyzing the overall health of your\n job more challenging.\n\nHow to use summaries\n--------------------\n\nTo ensure your import processes are recording conversions and enhancements as\nexpected, periodically retrieve the summaries for each of your accounts. If the\n`status` of any summary is not `EXCELLENT`, use the list of errors under\n`alerts` to guide you through modifying your import process to reduce or\neliminate those errors.\n\nFor example:\n\n- If the status is `NEEDS_ATTENTION`, then a significant portion of your\n import operations failed. Review the errors under `alerts` and modify your\n import process to reduce or eliminate those errors.\n\n- If the status is `NO_RECENT_UPLOADS`, then Google Ads has not received any recent\n imports for the `client`. If this is unexpected, then review the processes\n that perform imnports using that client.\n\n For example, if the `status` for `GOOGLE_ADS_API` is `NO_RECENT_UPLOADS`, that\n could indicate that your import process that uses the Google Ads API stopped running\n recently.\n- To determine if there was a specific import date or job that sent a large\n number of events that failed to process, check the `successful_count`,\n `failed_count`, and `pending_count` of `daily_summaries` and `job_summaries`.\n Any events in a pending state may take up to 24 hours\n to complete.\n\nMore information on how to improve offline data diagnostics can be found in\nthe [Help center](//support.google.com/google-ads/answer/13812240#4).\n\nRestrictions\n------------\n\nKeep the following in mind when retrieving import summaries:\n\n- The Google Ads API only returns offline data diagnostics if the\n [`customer_id`](/google-ads/api/reference/rpc/v21/SearchGoogleAdsStreamRequest#customer_id) of the\n `searchStream` or `search` request is the same customer you used recently to\n import conversions.\n\n For example, a client account that uses cross-account conversion tracking may\n not contain any diagnostics. However, you can retrieve diagnostics by sending\n a request where the `customer_id` matches the `customer_id` of the manager\n account you use in imports.\n- Google Ads treats `CLICK_NOT_FOUND` errors from [enhanced conversions for\n leads](/google-ads/api/docs/conversions/enhanced-conversions/leads) imports as warnings. As\n a result, if `alerts` contains an entry for this error, the corresponding\n operations are still considered successful and are included in the\n `successful_event_count`."]]
