报表最佳实践

先在界面中构建新报告

报告须遵守与报告类型、过滤条件、维度和指标相关的多项限制和要求。这些限制在 API 中强制执行，并会返回 HTTP 400 错误。为避免在构建报告时出错，我们建议您先在 Display & Video 360 界面中构建新报告。

构建报告后，点击参考文档页面上的“试用此 API”功能，对 Query 资源执行 queries.get。您可以使用返回的 JSON 来构建日后报告。

使用特定于报告类型的指标和过滤条件

某些指标和过滤条件值仅适用于特定报告类型。除了先在界面中构建报告之外，您还可以通过其出价管理器 API 值来识别属于特定 ReportType 值的指标和过滤条件。

下面介绍了一些用于识别相关 Bid Manager API 过滤条件和指标值的方法。此表并未详尽列出可在这些类型的报告中使用的过滤条件和指标。并非所有值都可以在单个报告中一起使用。

ReportType 相关的过滤条件和指标
YOUTUBE
  • 具有 FILTER_TRUEVIEW 前缀的过滤条件。
  • 前缀为 METRIC_TRUEVIEW 的指标。
GRP
  • 前缀为 METRIC_GRP 的指标。
YOUTUBE_PROGRAMMATIC_GUARANTEED
  • 具有 FILTER_YOUTUBE_PROGRAMMATIC_GUARANTEED 前缀的过滤器。
  • 前缀为 METRIC_PROGRAMMATIC_GUARANTEED 的指标。
REACH
  • 前缀为 METRIC_UNIQUE_REACH 的指标。
UNIQUE_REACH_AUDIENCE
  • 前缀为 METRIC_UNIQUE_REACH 的指标。

保存和重复使用报告

建议您为定期运行的查询创建并保存报告，因为多次插入和删除同一个报告会浪费资源。 在 dataRange 字段中使用设定的 Range 值（例如 PREVIOUS_DAY 或 LAST_7_DAYS）可以使报告更便于重复使用。

安排定期生成报告

临时报表（即一次性报表）会浪费资源，因为它们是单独生成的，而且可能是对不完整数据集执行的。定期生成的报表则可以充分利用报表资源，因为它们是批量生成的，而且可以保证在前一天的数据处理完毕后才执行。如需了解详情，请参阅在安排定期生成报表时可供使用的字段。

合并类似报告

如果您经常为不同的广告客户或合作伙伴生成指标和日期范围相同的报告，我们建议您合并这些报告，以优化报告量。

您可以通过附加所有报告的过滤条件并将所有过滤条件类型添加为维度，来组合类似的报告。生成报告后，您可以按原始过滤条件值拆分生成报告的行，以生成原始报告。

遵循报告配额

请负责任地使用 Display & Video 360 的报告功能，以确保遵循下列产品级用量配额。

每天的临时报表执行次数

限制用户在 24 小时内可以生成的临时报表的数量。 为避免超出此配额，请采取以下措施：

主动生成的定期报告

旨在限制用户可主动安排在给定时间生成的报表的数量。为避免超出此配额，请采取以下措施：

并发报告

限制用户可以同时生成的报告数量。 为避免超出此配额，请采取以下措施：

  • 安排定期生成报告。
  • 停用不必要的 API 脚本。
  • 使用指数退避逻辑轮询，跟踪报告生成的时间。

如果您已优化报告实现，但发现仍超出了给定配额，请使用联系表单与 Display & Video 360 支持团队联系。

轮询报告状态时使用指数退避算法

生成一个报表需要多长时间是无法预测的。生成报表所花费的时间可能从几秒到几小时不等，具体取决于许多因素，包括日期范围、要处理的数据量，等等。另外，生成报表所用的时间与报表中返回的行数之间也没有关联。因此，您需要定期使用 queries.reports.get 方法检索报告资源，并检查资源的 metadata.status.state 字段是否已更新为 DONE 或 FAILED，以确定报告是否已生成完毕。此过程称为“轮询”。

虽然轮询很有必要，但在遇到需要很长时间才能生成的报表时，如果编写的实现代码效率低下，可能很快就会耗尽您的配额。因此，我们建议您使用指数退避算法来限制重试次数，从而节省配额。

指数退避算法

指数退避算法是网络应用的标准错误处理策略，在此策略中，客户端按照不断增加的时间间隔定期重试请求。如果使用得当，指数退避算法还能提高带宽使用效率、减少获得成功响应所需的请求次数，并最大程度地提高并发环境中的请求吞吐量。

实现简单指数退避算法的流程如下：

  1. 向 API 发出 queries.reports.get 请求。
  2. 检索报告对象。如果 metadata.status.state 字段不是 DONE 或 FAILED，则表示报告尚未运行完毕，应继续轮询。
  3. 等待 5 秒 + 随机毫秒数，然后重试该请求。
  4. 检索报告对象。如果 metadata.status.state 字段不是 DONE 或 FAILED，则表示报告尚未运行完毕，应继续轮询。
  5. 等待 10 秒 + 随机毫秒数，然后重试该请求。
  6. 检索报告对象。如果 metadata.status.state 字段不是 DONE 或 FAILED，则表示报告尚未运行完毕，应继续轮询。
  7. 等待 20 秒 + 随机毫秒数，然后重试该请求。
  8. 检索报告对象。如果 metadata.status.state 字段不是 DONE 或 FAILED，则表示报告尚未运行完毕，应继续轮询。
  9. 等待 40 秒 + 随机毫秒数，然后重试该请求。
  10. 检索报告对象。如果 metadata.status.state 字段不是 DONE 或 FAILED，则表示报告尚未运行完毕，应继续轮询。
  11. 等待 80 秒 + 随机毫秒数，然后重试该请求。
  12. 一直持续此模式，直到报告对象更新或达到最大间隔时间为止。

如果报告运行完毕并以 DONE 状态结束，您可以从 Google Cloud Storage 中检索生成的报告文件，具体路径为 metadata.googleCloudStoragePath 字段中给出的路径。