このページは Cloud Translation API によって翻訳されました。

Cloud Storage を使ってみる

Google ディスプレイ &ビデオ 360 では、エンティティ読み取りファイルは Google Cloud Storage に自動的に保存されます。これらのファイルには、アクセス権が付与されているアカウントのみがアクセスできます。

プロジェクトを作成する

次のようにプロジェクトを作成して構成します。

Google API Console の [有効な API] ページに移動します。
Google にログインしていない場合は、ログインするよう求められます。
プロジェクトのプルダウンから、既存のプロジェクトを選択するか、新しいプロジェクトを作成します。
- 既存のプロジェクトが複数ある場合は、Google Cloud Storage を有効にするプロジェクトを選択し、[続行] を選択します。
- プロジェクトがない場合は、[新しいプロジェクトを作成] を選択し、プロジェクト名を入力して [作成] を選択します。
  注: 一部のリソース識別子（プロジェクト ID など）は、プロジェクトの存続期間を超えて保持される場合があります。そのため、リソース ID には機密情報を保存しないでください。
[有効な API] のリストに、Google Cloud Storage コンポーネントが表示されていることを確認します。リストにない場合は、[Google API] タブをクリックし、Google Cloud Storage コンポーネントを検索して選択して、[API を有効にする] をクリックします。
ほとんどのプロジェクトで、Google Cloud Storage コンポーネントはすでに有効になっています。JSON API を使用して Google Cloud Storage にアクセスする予定がある場合は、Google Cloud Storage JSON API が有効になっていることを確認します。
プロジェクトの課金を有効にします。
Google Cloud Storage を使用するには、プロジェクトの課金を有効にする必要があります（まだ有効にしていない場合）。課金を有効にしても、課金されるわけではありません。詳細については、料金をご覧ください。
1. Cloud Storage プロジェクトの左上隅にあるギャラリーメニューを開き、[お支払い] を選択します。
2. 請求先アカウントがない場合は、手順に沿って新しい請求先アカウントを作成します。
3. 既存の請求先アカウントがある場合は、それを選択して、[アカウントを設定] を選択します。

Google API Console で、同じプロジェクトのままで次のセクションに進みます。

Cloud Storage へのアクセス権を設定する

Google API Console で、必要なプロジェクト内の左上隅にあるギャラリーメニュー、[API とサービス]、[認証情報] の順にクリックします。[認証情報] ページで、サービスアカウントキーを探します。

サービスアカウントキーのメールアドレスを見つけます。
1. [サービスアカウントキー] セクションの右側にある [サービスアカウントの管理] リンクを選択します。
2. 表示される [権限] ページにメールアドレスが表示されます。
サービスアカウントキーがない場合は、新しいサービスアカウントを作成します。
1. [認証情報を作成] プルダウンをクリックし、[サービスアカウントキー] を選択します。
2. [サービスアカウント] プルダウンから [新しいサービスアカウント] を選択します。
3. [名前] にサービスアカウントの名前を入力します。サービスアカウント ID は、名前とプロジェクト名から自動的に生成されます。
4. サービスアカウント ID gserviceaccount.com のメールアドレスをメモしておきます。これは、[作成] を選択した後、[認証情報] ページには表示されません。
5. [キーのタイプ] セクションで、[JSON] を選択します。
6. [作成] をクリックします。アカウントの公開鍵/秘密鍵のペアを含む JSON ファイルが [ダウンロード] フォルダに保存されます。この鍵は、アプリケーションを API に対して認証し、API に送信するすべてのリクエストに署名するために使用されます。生成された JSON ファイルは、アプリがアクセスできる安全な場所に保管してください。
ディスプレイ &ビデオ 360 サポートチームにお問い合わせのうえ、エンティティ読み取りファイルや Google Bid Manager API の有効化を依頼してください。

サポートチームがアクセスを確認したら、専用の Google グループ（複数可）を作成し、ディスプレイ &ビデオ 360 のパートナーの詳細で以下の項目を更新します（これらの更新を行えるのは、パートナーレベルのアクセス権を持つユーザーのみです）。
- ログ読み取り Google グループ
  読み取り専用グループには、ファイルの読み取りとストレージバケットの内容の一覧表示のみの権限があります。
- ログ管理 Google グループ
  管理グループには読み取り専用グループのすべての権限がありますが、バケット内のファイルの ACL を変更することもできます。管理グループであっても、バケットの ACL を変更する権限はなく、ファイルを作成、変更、削除する権限もありません。
Google グループを追加した後は、ディスプレイ &ビデオ 360 サポートチームの関与なしに、必要に応じて Google グループに対してユーザーの追加や削除を行うことができます。データにアクセスできるのは、グループ内のユーザーのみです。

データへのアクセス

gsutil を使用してデータにアクセスする

gsutil ツールは、プログラミングの経験がなくても簡単に Google Cloud Storage のデータにアクセスできるコマンドラインアプリケーションです。たとえば、カスタムアプリケーションを作成する代わりに、gsutil をスクリプトやバッチファイルの一部として使用できます。

gsutil の使用を開始するには、gsutil のドキュメントをご覧ください。前と同様に、OAuth 2 を使用して認証を行う必要がありますが、gsutil 自体は、初めて認証情報を使用するときに認証情報の入力を求め、後で使用できるように保存します。

プログラムによるデータアクセス

Google Cloud Storage には、さまざまなプログラミング言語用の API が用意されており、プログラムでデータにアクセスできます。以下のサンプルは、Google Cloud Storage からいずれかのエンティティ読み取りファイルを簡単にダウンロードする方法を示しています。gdbm-public バケットに格納されるのは、一般公開されているエンティティ読み取りファイルのみです。非公開のエンティティ読み取りファイルは、パートナー固有バケットと広告主固有のバケットに保存されます。

Java

次の例では、Java 用の Google API クライアントライブラリを使用しています。これにより、Google Cloud Storage 内のデータに簡単にアクセスできます。メインの一般的な Google API クライアントライブラリに加えて、個別の Cloud Storage API 用のライブラリをダウンロードする必要があります。

まず、API との通信時に使用する認証情報を設定し、データへのアクセスを承認します。そのためには、Credential オブジェクトを作成します。このオブジェクトは、サービスアカウントの developer.gserviceaccount.com メールアドレスを ServiceAccountId として使用し、サービスアカウントの作成時に Google API Console からダウンロードした秘密鍵ファイルも読み込みます。これにより、今後 API に対するリクエストはすべて、サービスアカウントの秘密鍵で署名されます。

NetHttpTransport HTTP_TRANSPORT = new NetHttpTransport();
JacksonFactory JSON_FACTORY = new JacksonFactory();

...

Credential credential = new GoogleCredential.Builder().setTransport(HTTP_TRANSPORT)
   .setJsonFactory(JSON_FACTORY)
   .setServiceAccountId("...@developer.gserviceaccount.com")
   .setServiceAccountScopes(StorageScopes.DEVSTORAGE_READ_ONLY)
   .setServiceAccountPrivateKeyFromP12File(new File("...-privatekey.p12"))
   .build();

Credential オブジェクトを作成したら、そのオブジェクトを使用して新しい Storage オブジェクトをインスタンス化します。これは、今後 Google Cloud Storage API に対するすべてのリクエストに使用できます。

Storage storage = new Storage(HTTP_TRANSPORT, JSON_FACTORY, credential);

これで、新しい Storage オブジェクトが作成され、API へのリクエストを実行する準備が整いました。ここでは、バケット bucket から特定のアイテム bucketObjectName を取得するリクエストを行っています。このライブラリは、Google Cloud Storage からのファイルの HTTP ダウンロードを処理し、その内容をコンソールに出力します。

Get bucketObject = storage.objects().get(bucketName, bucketObjectName);

ByteArrayOutputStream output = new ByteArrayOutputStream();
bucketObject.getMediaHttpDownloader().setDirectDownloadEnabled(true);
bucketObject.executeAndDownloadTo(output);

System.out.println(output.toString());

bucket と bucketObjectName の値は、アクセスする API のどの部分であるかによって異なります。命名規則に関する該当するセクションをご覧ください。

C#

次の例では、.NET 用の Google API クライアントライブラリを使用しています。これにより、Google Cloud Storage 内のデータに簡単にアクセスできます。

まず、API との通信時に使用する認証情報を設定し、データへのアクセスを承認します。そのためには、AssertionFlowClient オブジェクトを作成します。このオブジェクトは、サービスアカウントの developer.gserviceaccount.com メールアドレスを ServiceAccountId として使用し、サービスアカウントの作成時に Google API Console からダウンロードした秘密鍵ファイルも読み込みます。

サービスアカウント用にダウンロードされた秘密鍵のパスワードは常に notasecret です。この値を変更する必要はありません。

string keyPath = @"...-privatekey.p12";
X509Certificate2 certificate = new X509Certificate2(keyPath, "notasecret", X509KeyStorageFlags.Exportable);
var provider = new AssertionFlowClient(GoogleAuthenticationServer.Description, certificate)
{
    ServiceAccountId = "...@developer.gserviceaccount.com",
    Scope = StorageService.Scopes.DevstorageRead_only.GetStringValue()
};

AssertionFlowClient オブジェクトを作成したら、そのオブジェクトを使用して新しい OAuth2Authenticator オブジェクトをインスタンス化します。このオブジェクトを使用して、今後の Google Cloud Storage API に対するすべてのリクエストで、新しい Storage インスタンスをインスタンス化できます。

var auth = new OAuth2Authenticator<AssertionFlowClient>(provider, AssertionFlowClient.GetState);
StorageService service = new StorageService(auth);

これで、新しい Storage オブジェクトが作成され、API へのリクエストを実行する準備が整いました。ここでは、バケット bucket から特定のアイテム bucketObjectName を取得するリクエストを行っています。Google では標準の .NET クライアントライブラリクラスを使用して、Google Cloud Storage からの HTTP ダウンロードを処理しますが、リクエストに常に正しい Authorization ヘッダーが含まれるように、リダイレクトがある場合は手動で処理する必要があります。

var results = service.Objects.Get(bucketName, bucketObjectName).Fetch();

HttpWebRequest request = createRequest(results.Media.Link, auth);
HttpWebResponse response = (HttpWebResponse)request.GetResponse();

// Handle redirects manually to ensure that the Authorization header is present if
// your request is redirected.
if (response.StatusCode == HttpStatusCode.TemporaryRedirect)
{
    request = createRequest(response.Headers["Location"], auth);
    response = (HttpWebResponse)request.GetResponse();
}

その後、レスポンスの内容は、通常どおり GetResponseStream を介して HttpWebResponse オブジェクトから読み取ることができます。bucket と bucketObjectName の値は、アクセスする API のどの部分であるかによって異なります。命名規則に関する該当するセクションをご覧ください。

付録: 完全なサンプル

Java

/*
 * Copyright (c) 2013 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0.
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.bidmanager.api.samples;

import java.io.BufferedReader;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.InputStreamReader;

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.storage.Storage;
import com.google.api.services.storage.Storage.Objects.Get;
import com.google.api.services.storage.StorageScopes;

/**
 * A simple class that demonstrates how to download a specific object from a bucket using a
 * service account
 */
public class ServiceDownload {

  /**
   * This is the HTTP Transport object used for automatically refreshing access tokens.
   */
  static final NetHttpTransport HTTP_TRANSPORT = new NetHttpTransport();

  /**
   * This is the JSON factory used for parsing refresh token responses.Your first requirement
   */
  static final JacksonFactory JSON_FACTORY = new JacksonFactory();

  /**
   * The main method will attempt to download a specific named object from the gdbm-public bucket
   * using a service account.
   *
   * @param args Not used.
   */
  public static void main(String[] args) {

    try {
      // Prompt the user for the details of the object to download.
      System.out.print("Name of object to download, e.g. entity/20130430.0.Browser.json:");
      BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
      String bucketObjectName = in.readLine();
      in.close();
      String bucketName = "gdbm-public";

      Credential credential = new GoogleCredential.Builder().setTransport(HTTP_TRANSPORT)
           .setJsonFactory(JSON_FACTORY)
           .setServiceAccountId("...@developer.gserviceaccount.com")
           .setServiceAccountScopes(StorageScopes.DEVSTORAGE_READ_ONLY)
           .setServiceAccountPrivateKeyFromP12File(
               new File("...-privatekey.p12"))
           .build();

      Storage storage = new Storage(HTTP_TRANSPORT, JSON_FACTORY, credential);

      Get bucketObject = storage.objects().get(bucketName, bucketObjectName);

      ByteArrayOutputStream output = new ByteArrayOutputStream();
      bucketObject.getMediaHttpDownloader().setDirectDownloadEnabled(true);
      bucketObject.executeAndDownloadTo(output);
      System.out.println(output.toString());

    } catch (Exception e) {
      System.err.println("Unexpected exception caught: " + e.getMessage());
      e.printStackTrace();
    }

  }


}

C#

/*
 * Copyright (c) 2013 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0.
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Net;
using System.Security.Cryptography.X509Certificates;

using DotNetOpenAuth.OAuth2;

using Google.Apis;
using Google.Apis.Requests;
using Google.Apis.Authentication.OAuth2;
using Google.Apis.Authentication.OAuth2.DotNetOpenAuth;
using Google.Apis.Storage.v1beta1;
using Google.Apis.Storage.v1beta1.Data;
using Google.Apis.Util;

namespace ApiSamples
{
    /// <summary>
    /// A simple class that demonstrates how to download a specific object from a bucket using a
    /// service account
    /// </summary>
    class ServiceDownload
    {
        /// <summary>
        /// The main method will attempt to download a specific named object from the
        /// gdbm-public bucket using a service account.
        /// </summary>
        /// <param name="args">Not used.</param>
        public static void Main(string[] args)
        {

            // Prompt the user for the details of the object to download
            Console.WriteLine("Name of object to download, e.g. entity/20130430.0.Browser.json:");
            string bucketObjectName = Console.ReadLine();
            string bucketName = "gdbm-public";

            try
            {
                string keyPath = @"...-privatekey.p12";
                X509Certificate2 certificate = new X509Certificate2(keyPath, "notasecret", X509KeyStorageFlags.Exportable);
                var provider = new AssertionFlowClient(GoogleAuthenticationServer.Description, certificate)
                {
                    ServiceAccountId = "...@developer.gserviceaccount.com",
                    Scope = StorageService.Scopes.DevstorageRead_only.GetStringValue()
                };
                var auth = new OAuth2Authenticator<AssertionFlowClient>(provider, AssertionFlowClient.GetState);

                StorageService service = new StorageService(auth);
                var results = service.Objects.Get(bucketName, bucketObjectName).Fetch();

                HttpWebRequest request = createRequest(results.Media.Link, auth);
                HttpWebResponse response = (HttpWebResponse)request.GetResponse();

                // Handle redirects manully to ensure that the Authorization header is present if
                // our request is redirected.
                if (response.StatusCode == HttpStatusCode.TemporaryRedirect)
                {
                    request = createRequest(response.Headers["Location"], auth);
                    response = (HttpWebResponse)request.GetResponse();
                }

                Stream stream = response.GetResponseStream();
                StreamReader reader = new StreamReader(stream);
                String data = reader.ReadToEnd();
                Console.Write(data);
            }
            catch (Exception e)
            {
                Console.WriteLine("Unexpected exception caught: " + e.Message);
                Console.Write(e.StackTrace);
            }
            Console.ReadKey();
        }

        /// <summary>
        /// Generate a HttpWebRequest for the given URL with the appropriate OAuth2 authorization
        /// header applied.  The HttpWebRequest object returned has its AllowAutoRedirect option
        /// disabled to allow us to manually handle redirects.
        /// </summary>
        /// <param name="url">URL that is to be requested with this object</param>
        /// <param name="auth">The OAuth2Authenticator instance that contains the appropriate keys.</param>
        /// <returns>HttpWebRequest object ready to be used to make requests to the API</returns>
        private static HttpWebRequest createRequest(string url, OAuth2Authenticator<AssertionFlowClient> auth)
        {
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
            request.Headers.Add("Authorization", "Bearer " + auth.State.AccessToken);
            request.AllowAutoRedirect = false;
            return request;
        }

    }
}