迁移到新版本

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

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

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

如果您怀疑自己维护的某款应用可能在使用 Campaign Manager 360 API 的已弃用版本,则应先确定您具体使用的是哪个版本。在大多数情况下,您都是通过我们针对特定语言的客户端库或某个官方集成来访问该 API 的。有关如何通过这些客户端库和集成确定所用 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_2
  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.3-rev1-1.21.0</version>
    </dependency>
  2. JAR 文件名中。
    google-api-services-dfareporting-v3.3-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 Builder 的参数:

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

Ruby

如果 Ruby 版本低于 0.9,则相应的 Google API 客户端库没有版本号。要使用的 API 版本会被指定为 Service Constructor 的参数:

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

如果 Ruby 版本是 0.9 或以上版本,则相应的 Google API 客户端库的版本信息位于服务命名空间中:

Google.Apis.DfareportingV3_2

请记下您目前使用的版本,因为稍后您会用到该信息。

第 2 步:确定版本的状态

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

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

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

第 3 步:升级版本

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

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.3', http=http)
有关详细的安装说明或其他下载方法,请参阅客户端库文档

Ruby

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

service = Google::APIClient::Service.new("dfareporting", "v3.3",
    {
      :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 资讯。