این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

با Cloud Storage شروع کنید

Google Display & Video 360 به‌طور خودکار فایل‌های خوانده شده موجودیت را در Google Cloud Storage ذخیره می‌کند. این فایل ها فقط برای حساب هایی قابل دسترسی هستند که به آنها اجازه دسترسی داده شده است.

یک پروژه ایجاد کنید

یک پروژه را به صورت زیر ایجاد و پیکربندی کنید:

به صفحه Google API Console Enabled APIs بروید.
اگر قبلاً وارد Google نشده اید، از شما خواسته می شود که وارد شوید.
از منوی کشویی پروژه، یک پروژه موجود را انتخاب کنید یا یک پروژه جدید ایجاد کنید.
- اگر چندین پروژه موجود دارید، مطمئن شوید که پروژه‌ای را که می‌خواهید Google Cloud Storage را برای آن فعال کنید، انتخاب کنید، سپس Continue را انتخاب کنید.
- یا اگر پروژه ای ندارید، ایجاد پروژه جدید را انتخاب کنید، نام پروژه را وارد کنید، سپس ایجاد را انتخاب کنید.
  توجه: باید توجه داشته باشید که برخی از شناسه‌های منابع (مانند شناسه پروژه) ممکن است تا پایان عمر پروژه شما حفظ شوند. به همین دلیل، از ذخیره اطلاعات حساس در شناسه های منابع خودداری کنید.
در فهرست APIهای فعال ، مطمئن شوید که مؤلفه Google Cloud Storage فهرست شده است. اگر در فهرست نیست، روی برگه Google APIs کلیک کنید، مؤلفه Google Cloud Storage را جستجو و انتخاب کنید و روی Enable API کلیک کنید.
توجه داشته باشید که برای اکثر پروژه‌ها، مؤلفه Google Cloud Storage قبلاً فعال است. اگر قصد دارید با استفاده از JSON API به Google Cloud Storage دسترسی پیدا کنید، باید تأیید کنید که Google Cloud Storage JSON API فعال است.
فعال کردن صورتحساب برای پروژه
قبل از اینکه بتوانید از Google Cloud Storage استفاده کنید، اگر قبلاً این کار را نکرده اید، باید صورتحساب پروژه خود را فعال کنید. فعال کردن صورتحساب لزوماً به این معنی نیست که از شما هزینه دریافت می شود. برای اطلاعات بیشتر، قیمت را ببینید.
1. هنوز در پروژه ذخیره سازی ابری هستید، روی منوی گالری در گوشه سمت چپ بالا کلیک کنید، سپس صورتحساب را انتخاب کنید.
2. اگر هنوز حساب صورت‌حساب ندارید، دستورالعمل‌ها را برای ایجاد یک حساب صورت‌حساب جدید دنبال کنید.
3. اگر یک حساب صورت‌حساب موجود دارید، آن را انتخاب کنید، سپس تنظیم حساب را انتخاب کنید.

در Google API Console، در همان پروژه بمانید و به بخش بعدی بروید.

دسترسی به فضای ذخیره‌سازی ابری را تنظیم کنید

هنوز در Google API Console در پروژه مورد نیاز، روی منوی گالری در گوشه سمت چپ بالا کلیک کنید، APIs & Services را انتخاب کنید و سپس روی Credentials کلیک کنید. در صفحه اعتبارنامه، به دنبال کلیدهای حساب سرویس بگردید.
آدرس ایمیل کلید حساب سرویس را پیدا کنید:
1. پیوند Manage Service Accounts (در سمت راست بخش کلیدهای حساب سرویس) را انتخاب کنید.
2. آدرس ایمیل در صفحه مجوزهای ایجاد شده قابل مشاهده است.
اگر هیچ کلید حساب سرویس وجود ندارد، یک حساب سرویس جدید ایجاد کنید:
1. منوی کرکره ای Create credentials را انتخاب کنید، سپس کلید حساب سرویس را انتخاب کنید.
2. در منوی کشویی حساب سرویس ، حساب سرویس جدید را انتخاب کنید.
3. یک نام برای حساب سرویس وارد کنید. شناسه حساب سرویس به طور خودکار از نام و نام پروژه ایجاد می شود.
4. شناسه حساب سرویس gserviceaccount.com آدرس ایمیل را یادداشت کنید . پس از انتخاب Create در صفحه اعتبارنامه ها نمایش داده نمی شود.
5. در بخش Key type ، JSON را انتخاب کنید.
6. روی ایجاد کلیک کنید. فایل JSON با جفت کلید عمومی/خصوصی حساب در پوشه Downloads شما ذخیره می‌شود. این کلید برای احراز هویت برنامه شما در API و امضای تمام درخواست هایی که به API ارسال می کند استفاده می شود. فایل JSON تولید شده را در مکانی امن ذخیره کنید، جایی که برنامه شما بتواند به آن دسترسی داشته باشد.
برای درخواست فعال کردن فایل‌های Entity Read و/یا Google Bid Manager API با تیم پشتیبانی Display & Video 360 تماس بگیرید.
پس از اینکه تیم پشتیبانی دسترسی را تأیید کرد، یک گروه (یا گروه‌های) Google اختصاصی ایجاد کنید و فیلدهای زیر را در جزئیات شریک Display & Video 360 به‌روزرسانی کنید (توجه داشته باشید که فقط کاربرانی که دسترسی در سطح شریک دارند می‌توانند این به‌روزرسانی‌ها را انجام دهند):
- ورود به سیستم Read Google Group
  گروه فقط خواندنی فقط مجوز خواندن فایل ها و فهرست کردن محتوای سطل های ذخیره سازی را دارد.
- مدیریت ورود به سیستم Google Group
  گروه مدیریت تمام مجوزهای گروه فقط خواندنی را دارد، اما همچنین می‌تواند ACL فایل‌های درون سطل‌ها را تغییر دهد. توجه داشته باشید که حتی گروه مدیریت مجوز تغییر سطل ACL و همچنین اجازه ایجاد، تغییر یا حذف فایل ها را ندارند.
پس از اضافه شدن گروه Google، می‌توانید بدون دخالت بیشتر تیم پشتیبانی Display & Video 360، کاربران را به گروه Google خود اضافه کرده و در صورت نیاز از آنها حذف کنید. فقط کاربرانی که در گروه شما هستند به داده های شما دسترسی خواهند داشت.

به داده های خود دسترسی داشته باشید

با استفاده از gsutil به داده ها دسترسی پیدا کنید

ابزار gsutil یک برنامه خط فرمان است که به شما امکان می دهد به راحتی و بدون تجربه برنامه نویسی به داده های Google Cloud Storage خود دسترسی داشته باشید. برای مثال، می‌توانید از gsutil به‌عنوان بخشی از یک اسکریپت یا فایل دسته‌ای به جای ایجاد برنامه‌های سفارشی استفاده کنید.

برای شروع با gsutil، مستندات gsutil را بخوانید. شما همچنان باید مانند قبل با استفاده از OAuth 2 احراز هویت کنید، اما خود gsutil اولین بار که از آن استفاده می کنید اعتبارنامه ها را از شما می خواهد و سپس آنها را برای استفاده در آینده ذخیره می کند.

دسترسی به داده ها به صورت برنامه ای

Google Cloud Storage دارای API برای بسیاری از زبان‌های برنامه‌نویسی است که به شما امکان می‌دهد به روش برنامه‌نویسی به داده‌های خود دسترسی داشته باشید. نمونه زیر به شما نشان می‌دهد که چگونه می‌توانید دانلود ساده یکی از فایل‌های Entity Read از Google Cloud Storage را انجام دهید. به یاد داشته باشید که فقط فایل های عمومی Entity Read در سطل gdbm-public ذخیره می شوند. فایل‌های خوانده شده نهاد خصوصی شما در سطل‌های خاص شریک و تبلیغ‌کننده ذخیره می‌شوند.

جاوا

مثال زیر از Google APIs Client Library برای جاوا استفاده می کند که دسترسی به داده های ذخیره شده در Google Cloud Storage را آسان می کند. علاوه بر کتابخانه اصلی Google APIs Client Library، باید کتابخانه جداگانه برای Cloud Storage API را نیز دانلود کنید.

ابتدا باید اعتبارنامه هایی را تنظیم کنید تا در هنگام برقراری ارتباط با API از آنها استفاده کنید تا مجوز دسترسی به داده های خود را دریافت کنید. این کار با ایجاد یک شئ Credential انجام می شود که از آدرس ایمیل حساب کاربری developer.gserviceaccount.com به عنوان ServiceAccountId استفاده می کند و همچنین فایل کلید خصوصی را که هنگام ایجاد حساب سرویس از کنسول API Google دانلود شده است بارگیری می کند. این اطمینان حاصل می کند که تمام درخواست های آینده به 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 هستید. در اینجا شما درخواستی برای بازیابی یک مورد خاص bucketObjectName از bucket سطل دارید. کتابخانه بارگیری HTTP فایل را از Google Cloud Storage انجام می‌دهد و شما به سادگی محتویات آن را در کنسول چاپ می‌کنید:

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 که به آن دسترسی دارید متفاوت خواهد بود. به بخش مناسب در مورد قراردادهای نامگذاری مراجعه کنید.

سی شارپ

مثال زیر از Google APIs Client Library برای دات نت استفاده می کند که دسترسی به داده های ذخیره شده در Google Cloud Storage را ساده و آسان می کند.

ابتدا باید اعتبارنامه هایی را تنظیم کنید تا در هنگام برقراری ارتباط با API از آنها استفاده کنید تا مجوز دسترسی به داده های خود را دریافت کنید. این کار با ایجاد یک شی AssertionFlowClient انجام می شود که از آدرس ایمیل developer.gserviceaccount.com سرویس حساب به عنوان ServiceAccountId استفاده می کند و همچنین فایل کلید خصوصی را که هنگام ایجاد حساب سرویس از کنسول API Google دانلود شده است بارگیری می کند.

رمز عبور کلیدهای خصوصی دانلود شده برای حساب های خدماتی همیشه 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 جدید استفاده کنید که می توانید از آن برای نمونه سازی یک نمونه Storage جدید برای همه درخواست های آینده به Google Cloud Storage API استفاده کنید:

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

اکنون که یک شی Storage جدید دارید، آماده شروع درخواست برای API هستید. در اینجا شما در حال درخواست برای بازیابی یک مورد خاص، bucketObjectName ، از bucket سطل هستید. ما از کلاس‌های کتابخانه کلاینت دات‌نت استاندارد برای مدیریت دانلود HTTP از Google Cloud Storage استفاده می‌کنیم، اما باید به صورت دستی مواردی را که تغییر مسیر وجود دارد رسیدگی کنید تا اطمینان حاصل کنید که همیشه سرصفحه 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();
}

سپس محتویات پاسخ را می توان طبق معمول از شی HttpWebResponse از طریق GetResponseStream خواند. مقادیر شما برای bucket و bucketObjectName بسته به قسمتی از API که به آن دسترسی دارید متفاوت خواهد بود. به بخش مناسب در مورد قراردادهای نامگذاری مراجعه کنید.

ضمیمه: نمونه های کامل

جاوا

/*
 * 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();
    }

  }


}

سی شارپ

/*
 * 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;
        }

    }
}