Campaign Manager 360 API v3.4 已被弃用,并将于 2022 年 1 月 10 日停用。所有用户都必须在该截止日期之前迁移到新版 API。

迁移到新版本

我们会定期发布 Campaign Manager 360 API 的新版本。随着新版本的不断发布,我们会弃用并最终停用较旧的版本。停用某个版本后,针对该版本的所有请求都会开始返回错误。

如果您目前使用的 API 版本已被弃用,您将需要在预定的停用日期之前迁移到较新的版本。本指南详细介绍了如何确定您目前使用的 API 版本是否已被弃用,并提供了建议的迁移步骤。

第 1 步:确定您目前使用的版本

如果您怀疑自己维护的某款应用可能在使用 Campaign Manager 360 API 的已弃用版本,则应先确定您具体使用的是哪个版本。在大多数情况下,您都是通过我们适用于某种语言的客户端库或某种官方集成来使用该 API 的。下面按客户端库和集成列出了有关如何确定当前所用 API 版本的说明:

Apps 脚本新版编辑器

您可以在高级服务对话框中找到 Apps 脚本所用的版本信息:

  1. 在 Apps 脚本编辑器中,点击添加服务
  2. 在可用服务列表中找到 Campaign Manager 360 API。
  3. 版本下拉菜单中选定的值即为目前正在使用中的 Campaign Manager 360 API 版本。

Apps 脚本旧版编辑器

您可以在高级服务对话框中找到 Apps 脚本所用的版本信息:

  1. 在 Apps 脚本编辑器中,依次转到资源 > 高级 Google 服务
  2. 在可用服务列表中找到 Campaign Manager 360 API。
  3. 版本下拉菜单中选定的值即为目前正在使用中的 Campaign Manager 360 API 版本。

C#

您可以在以下位置找到适用于 .NET 的 Google API 客户端库的版本信息:

  1. Nuget 软件包名称和服务命名空间中。
    Google.Apis.Dfareporting.v3_4
  2. 通过 DfareportingService 的公共属性加以公开。
    Console.WriteLine(DfareportingService.Version);

Java

您可以在以下位置找到适用于 Java 的 Google API 客户端库的版本信息:

  1. Maven artifactId 中。
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-dfareporting</artifactId>
      <version>v3.4-rev1-1.21.0</version>
    </dependency>
  2. JAR 文件名中。
    google-api-services-dfareporting-v3.4-rev1-1.21.0.jar
  3. 通过 Dfareporting 的公共属性加以公开。
    System.out.println(Dfareporting.DEFAULT_SERVICE_PATH);

PHP

适用于 PHP 的 Google API 客户端库的版本信息通过 Google_Client_Dfareporting 的公共属性加以公开:

$service = new Google_Client_Dfareporting($client)
print $service->version;

Python

适用于 Python 的 Google API 客户端库没有版本号。要使用的 API 版本作为 discovery 类的构建函数的一个参数加以指定:

discovery.build('dfareporting', 'v3.4', http=http)

Ruby

如果 Ruby 版本低于 0.9,则相应的 Google API 客户端库没有版本号。这种情况下,要使用的 API 版本作为 Service 类的构造函数的一个参数加以指定:

service = Google::APIClient::Service.new("dfareporting", "v3.4",
    {
      :application_name => "My application",
      :application_version => '1.0.0',
      :authorization => authorization
    }
)

如果 Ruby 版本是 0.9 或以上版本,则相应 Google API 客户端库的版本信息通过服务命名空间加以公开:

Google.Apis.DfareportingV3_4

请记下您目前使用的版本,因为在后面的步骤中需要用到该信息。

第 2 步:确定您所用版本的状态

弃用时间表中列出了目前支持的每个版本的状态。请从该列表中找到您使用的版本,并按照下列说明确定其状态:

  1. 如果弃用日期停用日期列中未列出任何日期,则说明您使用的是完全受支持的版本。
  2. 如果这些列中列出了日期,则说明您使用的版本目前已被弃用,并将于指定日期停用。
  3. 如果您的版本未列在其中,则说明该版本已被停用,且不再受支持。

如果您目前使用的版本符合上述第 2 条或第 3 条的情况,那么您需要迁移到较新的版本,以免服务出现中断。建议您迁移到弃用时间表顶部列出的最新版本(Beta 版除外),以便尽可能推迟需要再次升级的时间。

第 3 步:升级版本

如果您已确定需要进行迁移,接下来就需要更新您的集成,或获取首选客户端库的新 build。请注意,有些客户端库可能只提供一个适用于所有 API 版本的 build,有些则针对每个 API 版本分别提供单独的 build。以下列表中提供了使用最广泛的客户端库和集成的常规升级信息。

Apps 脚本新版编辑器

Google Apps 脚本支持 Campaign Manager 360 API 的所有版本,可让您根据脚本选择要使用的版本。如需更改特定脚本使用的版本,请执行以下操作:

  1. 在 Apps 脚本编辑器中,点击添加服务
  2. 在可用服务列表中找到 Campaign Manager 360 API。
  3. 通过版本下拉菜单更改正在使用的 Campaign Manager 360 API 版本。
  4. 点击添加以保存更改。

Apps 脚本旧版编辑器

Google Apps 脚本支持 Campaign Manager 360 API 的所有版本,可让您根据脚本选择要使用的版本。如需更改特定脚本使用的版本,请执行以下操作:

  1. 在 Apps 脚本编辑器中,依次转到资源 > 高级 Google 服务
  2. 在可用服务列表中找到 Campaign Manager 360 API。
  3. 通过版本下拉菜单更改正在使用的 Campaign Manager 360 API 版本。
  4. 点击确定以保存您的更改。

C#

适用于 .NET 的 Google API 客户端库针对 Campaign Manager 360 API 的每个版本分别提供单独的 build,并通过 Nuget 分发。

有关详细的安装说明或其他下载方法,请参阅客户端库文档

Java

适用于 Java 的 Google API 客户端库针对 Campaign Manager 360 API 的每个版本分别提供单独的 build,并通过 Maven 分发。

有关详细的安装说明或其他下载方法,请参阅客户端库文档

PHP

适用于 PHP 的 Google API 客户端库针对 Campaign Manager 360 API 的每个版本分别提供单独的 build,并通过 Packagist 分发。

有关详细的安装说明或其他下载方法,请参阅客户端库文档

Python

适用于 Python 的 Google API 客户端库的每个 build 均支持 Campaign Manager 360 API 的所有版本。只需更新作为 Discovery 类的构建函数的一个参数传递的版本字符串即可:

discovery.build('dfareporting', 'v3.4', http=http)
有关详细的安装说明或其他下载方法,请参阅客户端库文档

Ruby

适用于 Ruby v0.8 及更低版本的 Google API 客户端库支持 Campaign Manager 360 API 的所有版本。只需更新作为服务构造函数的参数传递的版本字符串即可:

service = Google::APIClient::Service.new("dfareporting", "v3.4",
    {
      :application_name => "My application",
      :application_version => '1.0.0',
      :authorization => authorization
    }
)
适用于 Ruby v0.9 及更高版本的 Google API 客户端库针对 Campaign Manager 360 API 的每个版本分别提供单独的 build,并通过 RubyGems 分发。有关详细的安装说明或其他下载方法,请参阅客户端库文档

第 4 步:解决版本差异问题

我们会全力确保新发布的版本具有向后兼容性,让您在不同的 API 版本之间迁移时,无需对代码进行更改。当有时候无法做到这一点时,我们会在版本说明中注明需要开发者采取行动的具体更改(也称为破坏性更改)。

这种情况下,您应查看我们的版本说明,从您一开始使用的版本(您在前面的部分中记下的版本)的下一版本开始,一直看到您要升级到的版本。以下是对版本说明各个部分的解释:

  • 新功能 - 新添加的功能。
  • 停用 - 已从该 API 中移除的功能。如果有替换功能,则会在这一部分进行介绍。
  • 已知问题 - 不属于功能添加或功能移除情况的更改。例如,此部分可能会介绍已改名的字段或方法,或有变更的验证逻辑。

对于新功能中的功能,无需进行代码更改,因此可以暂时忽略。如果之后您想试试我们添加的某些功能,可以随时再回来参阅此部分。

另一方面,如果您在停用已知问题部分发现有更改,您可能需要采取行动。您应在自己的代码中进行搜索,以确定您的应用是否使用了任何已移除或已修改的功能。如果您的应用使用了此类功能,您将需要根据这些变化更新您的代码。

掌握最新动态

如前所述,我们会定期发布 Campaign Manager 360 API 的新版本并停用较旧的版本。您可以通过下列渠道了解新版本、弃用和停用方面的最新资讯:

建议您订阅上述一个或多个渠道,及时了解最新的 API 资讯。