访问 Ad Manager 存储分区

如何下载数据传输文件

Google Cloud Storage 是一款独立的 Google 产品,供 Ad Manager 用作数据传输报表批量上传的受众群体 Cookie ID 的数据存储区。

本文旨在让您了解如何将标准的 Google Cloud Storage 技术与 Ad Manager 的特定云端存储设置搭配使用。不过,对于 Google Cloud Storage,您应主要参考 Google Cloud Storage 开发者网站

方法

您可通过 3 种方法访问 Ad Manager 云端存储分区。下文按照从易到难的顺序列出了这些方法:

  • 在网页上:访问 https://console.developers.google.com/storage/gdfp-[Ad Manager 广告联盟代码]
  • gsutil 是一种基于 Python 的命令行工具,可提供类似于 Unix 的命令以与相应的存储分区交互。存储分区身份验证的抽象化和处理都是自动进行的。
  • Google Cloud Storage API 是一种用于操控存储分区的全功能 API,可通过 JSON 或 XML RESTful 网络界面使用。API 客户端库可用于许多常用的编程环境,包括 Java、JavaScript、Python 和 Objective-C。如果您需要以编程方式操控存储分区,从而与 Google App 引擎应用或 Java 网络应用进行集成,则这种方法最有效。

本文提供了有关 Google Cloud Storage API 的详情。由于通过网络和 gsutil 进行访问的可行性更强,因此我们首推这两种方法。Google Cloud Storage 开发者网站中充分介绍了这两种方法。

管理对 Ad Manager 存储分区的访问权限

Ad Manager 使用的存储分区包含在 Google 拥有的云端存储项目中。Ad Manager 存储分区不会显示在 Google Developers Console 中您自己的项目列表内。

当您与 Google 代表一起设置依赖 Ad Manager 存储分区的功能时,您需要创建一个 Google 网上论坛,以便管理对您的存储分区的访问权限。网上论坛成员可以拥有只读权限或读写权限,具体取决于您使用的功能。

如果您本人将是相应网上论坛的管理员,请自行按照以下说明操作。如果管理员将是别人,请确保此人登录到正确的 Google 帐号并按照以下说明操作。

要创建 Google 网上论坛,请执行以下操作:

  1. 转到 http://groups.google.com/,然后按照说明新建一个网上论坛。

    网上论坛的命名惯例由您自行决定,但我们建议您在命名时添加主要 Google Marketing Platform 产品的名称、您的广告联盟 ID 和公司名称。示例:admanager-9999-BigCompany。
  2. 向该 Google 网上论坛添加用户。我们建议您使用用户在访问 Ad Manager 时所用的电子邮件地址;建议您不要使用个人电子邮件地址。

  3. 在启用相应功能的过程中,将您的 Google 网上论坛的名称告知 Google。Google 会与您一起启用使用 Ad Manager 存储分区的所有功能。

使用 Google Cloud Storage API

如果您已确定 API 访问权限最符合您的需求,我们建议您配置一个 Google 云端存储服务帐号。

配置 Google 云端存储服务帐号

通过 API 访问存储分区时,最好配置一个服务帐号,而不是在用户环境中运行。服务帐号会使用私钥(而不是动态生成的 OAuth 令牌)进行身份验证,这便简化了应用开发工作。要配置服务帐号,请执行以下操作:

  1. 转到 Google Developers Console

  2. 创建一个新项目(或选择一个现有项目)作为应用的父级项目,然后点击进入该项目。

  3. (可选)如果您打算将文件从 Ad Manager 存储分区复制到您自己的 Google Cloud Storage 帐号,请点击结算和设置,以便向您的项目添加结算来源。

  4. 新建一个客户端 ID:

    1. 依次点击 API 和服务验证 > 凭据

    2. 点击新建客户端 ID

    3. 选择服务帐号作为应用类型,然后点击创建客户端 ID

    4. 系统所生成的电子邮件地址会采用如下格式:[唯一 ID]@developer.gserviceagccount.com。请复制此电子邮件地址并妥善保存,以便稍后将其添加到您的 Google 网上论坛中。

    5. 点击生成新的 P12 密钥。该文件会自动保存到您的计算机中。您可在自己开发的应用中使用此密钥来访问 API,如下文中的代码示例所示。

  5. 将您保存的电子邮件地址添加到您创建的 Google 网上论坛,以管理对您的 Ad Manager 存储分区的访问权限。请点击直接添加成员(而非“邀请”)来添加服务帐号。如果您没有相关权限,请让 Google 网上论坛管理员代您添加地址。
代码示例

Google 提供了 Google Cloud Storage 的代码示例和库。下面的 Java 示例用于读取 Ad Manager 云端存储分区中的某个文件。该示例显示了您在设置服务帐号时配置的组件可能会对代码产生哪些影响:

  • 项目名称:Google Cloud Storage 项目的名称。

  • 服务帐号电子邮件地址:您生成的电子邮件地址。

  • .p12 密钥文件:您下载的文件。

  • 存储分区名称:当您启用使用 Ad Manager 云端存储分区的功能时,Google 会向您提供此名称。

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.storage.Storage;
import com.google.api.services.storage.model.StorageObject;

public class GcsApiTest {
    /**
     * 在其下创建了服务帐号的项目的名称。
     * 
     * 此信息显示在 Google Developers Console 下。
     */
    private static final String PROJECT_NAME = "project name";

    /**
     * 服务帐号的开发者电子邮件地址。
     * 
     * 此电子邮件在您在 Google Developers Console 中
     * 创建服务帐号客户端 ID 后生成,您可以从“凭据”
     * 页面检索此电子邮件。您还必须向 Google 网上论坛添加此电子邮件地址,
     * 该网上论坛用于控制对存储分区的访问权限。
     */
    private static final String SERVICE_ACCOUNT_EMAIL = "service account email address";

    /**
     * 用于存储操作的存储分区。
     * 
     * 您的客户经理向您提供了此存储分区的名称。
     * 它的名称类似于“gdfp-12345678”或
     * “gdfp_cookieupload_12345678”,这取决于您使用的 Ad Manager 插件。
     */
    private static final String BUCKET_NAME = "bucket name";

    /**
     * Google Cloud Storage OAuth 2.0 读/写范围。

     * 该访问权限指的应是 Google 网上论坛对存储分区的访问权限,
     * 而且您不能请求获得未授予
     * 此网上论坛的访问权限(可能是 read_only)。
     */
    private static final String STORAGE_SCOPE = 
        "https://www.googleapis.com/auth/devstorage.read_write";

    /**
     * 提供该存储分区访问权限的 key.p12 文件的路径。
     * 
     * 此文件在您创建服务客户端 ID 后生成。如果您没有
     * 此文件,则需要从 Google Developers Console
     * 生成新的客户端 p12 密钥。
     */
    private static final String KEY_P12 = "path to .p12 key file";

    /** HTTP 传输。*/
    private HttpTransport httpTransport;
    private Storage storage;

    // 简单构造函数,创建凭据和存储对象
    public GcsApiTest() {
	File p12File = new File(KEY_P12);

	try {
	    httpTransport = GoogleNetHttpTransport.newTrustedTransport();

	    GoogleCredential credential = new GoogleCredential.Builder()
		    .setTransport(httpTransport)
		    .setJsonFactory(JacksonFactory.getDefaultInstance())
		    .setServiceAccountId(SERVICE_ACCOUNT_EMAIL)
		    .setServiceAccountScopes(
			    Collections.singleton(STORAGE_SCOPE))
		    .setServiceAccountPrivateKeyFromP12File(p12File).build();
	    storage = new Storage.Builder(httpTransport,
		    JacksonFactory.getDefaultInstance(), credential)
		    .setApplicationName(PROJECT_NAME).build();
	} catch (GeneralSecurityException | IOException e1) {
	    e1.printStackTrace();
	    System.exit(1);
	}
    }

    /**
     * 用于返回存储分区中第一个文件的名称的简单方法。
     * 
     * @返回该文件的名称,如果存储分区为空,则返回 null
     * @引发 IOException
     */
    public String GetFirstFile() throws IOException {
	Storage.Objects.List listObjects = storage.objects().list(BUCKET_NAME);
	listObjects.setMaxResults(5L);
	com.google.api.services.storage.model.Objects objects = listObjects
		.execute();

	// 存储分区为空?
	if (null == objects.getItems() || objects.getItems().isEmpty()) {
	    System.out.println("Bucket \"" + BUCKET_NAME
		    + "\" empty or invalid.");
	    return null;
	}

	StorageObject object = objects.getItems().get(0);
	System.out.println("First object in bucket: \"" + object.getName()
		+ "\".");
	return object.getName();
    }

    /**
     * 简单方法,用于从存储分区下载指定文件
     * 
     * @参数文件名
     *            应下载的文件的名称。
     * @引发 IOException
     */
    public void DownloadFile(String filename) throws IOException {
	Storage.Objects.Get getObject = storage.objects().get(BUCKET_NAME,
		filename);
	OutputStream os = new FileOutputStream(filename, true);
	getObject.getMediaHttpDownloader().setDirectDownloadEnabled(true);
	getObject.executeMediaAndDownloadTo(os);

	System.out.println("File \"" + filename + "\" downloaded.");
    }

    /**
     * 用于执行不同测试的主方法。
     * 
     * @形参 实参
     */
    public static void main(String[] args) {
	GcsApiTest gcsApiTest = new GcsApiTest();

	try {
	    String filename = gcsApiTest.GetFirstFile();
	    gcsApiTest.DownloadFile(filename);
	} catch (IOException e) {
	    System.out.println(e.getMessage());
	}
    }
}

限制和并发连接数

尽管没有预定义的并发连接数限制,但为了避免滥用行为,Google 对数据传输提取请求数设定了限制。

要了解最新资讯,请查看 Google 代码官方博客的“Google Cloud Storage”版块;您也可在 Google Cloud Storage 论坛中发帖提问。请酌情在主题行中添加“错误”或“功能请求”字样。如果您对 Google 云端存储还有其他疑问,请参阅 Google 云端存储常见问题解答
该内容对您有帮助吗?
您有什么改进建议?