بدء استخدام Cloud Storage

تخزِّن "مساحة العرض والفيديو 360" تلقائيًا ملفات "قراءة الكيانات" في Google Cloud Storage. لا يمكن الوصول إلى هذه الملفات إلا من خلال الحسابات التي تم منحها إذن الوصول.

يُرجى العلم بأنّ حِزم Cloud Storage التي تحتوي على ملفات "قراءة الكيانات" الخاصة بك وجميع بيانات "مساحة العرض والفيديو 360 من Google" ترتبط بمشروع على Google API Console تملكه من خلال "مساحة العرض والفيديو 360". إنّ سياسة الاحتفاظ بالبيانات في الحِزم في هذا المشروع هي 180 يومًا.

إنشاء مشروع

يمكنك إنشاء مشروع وضبطه على النحو التالي:

1. انتقِل إلى صفحة واجهات برمجة التطبيقات التي تم تفعيلها من خلال وحدة تحكّم Google API.

   إذا لم تكن قد سجّلت دخولك إلى Google، فسيُطلب منك تسجيل الدخول.

2. من القائمة المنسدلة للمشروع، اختَر مشروعًا حاليًا أو أنشئ مشروعًا جديدًا.
   • إذا كانت لديك عدة مشاريع حالية، تأكّد من اختيار المشروع الذي تريد تفعيل Google Cloud Storage له، ثم انقر على متابعة.
   • إذا لم يكن لديك مشروع، اختَر إنشاء مشروع جديد وأدخِل اسم مشروع، ثم اختَر إنشاء.

     ملاحظة: يجب أن تدرك أنّ بعض معرّفات الموارد (مثل أرقام تعريف المشاريع) قد يتم الاحتفاظ بها لمدة أطول من تاريخ مشروعك. ولهذا السبب، تجنَّب تخزين المعلومات الحسّاسة في معرّفات الموارد.

3. في قائمة واجهات برمجة التطبيقات المفعَّلة، تأكَّد من إدراج مكوِّن Google Cloud Storage. وإذا لم تكن مُدرَجة، انقر على علامة التبويب Google APIs وابحث عن مكوِّن Google Cloud Storage واختَره، ثم انقر على تفعيل واجهة برمجة التطبيقات.

   تجدر الإشارة إلى أنّه قد سبق تفعيل مكوّن Google Cloud Storage لمعظم المشاريع. إذا كنت تريد الوصول إلى Google Cloud Storage باستخدام JSON API، عليك أيضًا التأكّد من أنّ واجهة Google Cloud Storage JSON API مفعّلة.

4. تفعيل الفوترة للمشروع

   قبل أن تتمكّن من استخدام Google Cloud Storage، عليك تفعيل الفوترة لمشروعك إذا لم يسبق لك تفعيلها، علمًا أنّ تفعيل الفوترة لا يعني بالضرورة تحصيل رسوم منك. لمزيد من المعلومات، يُرجى الاطّلاع على التسعير.

   1. إذا كنت لا تزال داخل مشروع التخزين في السحابة الإلكترونية، انقر على قائمة المعرض في أعلى يمين الصفحة، ثم اختَر الفوترة.
   2. إذا لم يكن لديك حساب فوترة حتى الآن، اتّبِع التعليمات لإنشاء حساب فوترة جديد.
   3. إذا كان لديك حساب فوترة حالي، اختَره ثم انقر على ضبط الحساب.

في وحدة التحكم في واجهة Google API، ابقَ ضمن المشروع نفسه وانتقِل إلى القسم التالي.

إعداد الوصول إلى Cloud Storage

1. في وحدة تحكم Google API ضمن المشروع المطلوب، انقر على قائمة المعرض في الزاوية العلوية اليمنى، واختر واجهات برمجة التطبيقات والخدمات، ثم انقر على بيانات الاعتماد. في صفحة "بيانات الاعتماد"، ابحث عن مفاتيح حساب الخدمة.

   ابحث عن عنوان البريد الإلكتروني لمفتاح حساب الخدمة:

   1. اختر الرابط إدارة حسابات الخدمة (على يسار قسم مفاتيح حساب الخدمة).
   2. ويمكن عرض عنوان البريد الإلكتروني في صفحة الأذونات الناتجة.

   إذا لم تكن هناك مفاتيح لحساب الخدمة، أنشئ حساب خدمة جديدًا:

   1. اختَر القائمة المنسدلة إنشاء بيانات اعتماد، ثم اختَر مفتاح حساب الخدمة.
   2. في القائمة المنسدلة حساب الخدمة، اختَر حساب خدمة جديد.
   3. أدخِل اسمًا لحساب الخدمة. يتم إنشاء رقم تعريف حساب الخدمة تلقائيًا من الاسم واسم المشروع.
   4. دوِّن رقم تعريف حساب الخدمة gserviceaccount.com عنوان البريد الإلكتروني. ولن يتم عرضه في صفحة "بيانات الاعتماد" بعد اختيار إنشاء.
   5. في قسم نوع المفتاح، اختَر JSON.
   6. انقر على إنشاء. يتم حفظ ملف JSON الذي يتضمّن زوج المفاتيح العام/الخاص بالحساب في مجلد "عمليات التنزيل". يُستخدم هذا المفتاح لمصادقة تطبيقك بواجهة برمجة التطبيقات وتوقيع جميع الطلبات التي يرسلها إلى واجهة برمجة التطبيقات. عليك تخزين ملف JSON الذي تم إنشاؤه في مكان آمن، حيث يمكن لتطبيقك الوصول إليه.

2. يمكنك التواصل مع فريق دعم "مساحة العرض والفيديو 360" لطلب تفعيل ملفات "قراءة الكيانات" و/أو Google Bid Manager API.

   بعد تأكيد فريق الدعم إذن الوصول، أنشئ مجموعة Google (أو مجموعات) مخصّصة وعدِّل الحقول التالية في تفاصيل شريك "مساحة العرض والفيديو 360" (يُرجى العلم أنّه لن يتمكن من إجراء هذه التعديلات سوى المستخدمين الذين لديهم إذن وصول على مستوى الشريك):

   • مجموعة Google المخصَّصة للقراءة فقط
     تمتلك المجموعة المخصّصة للقراءة فقط أذونات لقراءة الملفات وإدراج محتوى حِزم التخزين.
   • مجموعة Google لإدارة السجلّات
     تملك مجموعة الإدارة جميع الأذونات الخاصة بالمجموعة للقراءة فقط، ولكن يمكنها أيضًا تغيير قوائم التحكم بالوصول (ACL) للملفات ضمن الحِزم. لاحظ أنه حتى مجموعة الإدارة ليس لديها إذن لتغيير قوائم التحكم في الوصول (ACL)، وليس لديها إذن بإنشاء الملفات أو تعديلها أو حذفها.

   بعد إضافة "مجموعة Google"، يمكنك إضافة مستخدمين إلى "مجموعة Google" وإزالتهم منها حسب الحاجة بدون أي مشاركة أخرى من فريق دعم "مساحة العرض والفيديو 360"، ولن يتمكّن سوى هؤلاء المستخدمين في مجموعتك من الوصول إلى بياناتك.

الوصول إلى بياناتك

لتنفيذ هذا النوع من عمليات الدمج، يجب أولاً إضافة عنوان البريد الإلكتروني لحساب الخدمة إلى مجموعة البريد الإلكتروني الحاصلة على إذن للحساب من خلال واجهة مستخدم DBM.

الوصول إلى البيانات باستخدام أداة gsutil

إنّ أداة gsutil هو تطبيق سطر أوامر يتيح لك الوصول إلى بيانات Google Cloud Storage بسهولة بدون أي خبرة في البرمجة. يمكنك مثلاً استخدام أداة gsutil كجزء من نص برمجي أو ملف مجمّع بدلاً من إنشاء تطبيقات مخصَّصة.

لبدء استخدام gsutil، عليك قراءة مستندات gsutil. ستظل بحاجة إلى المصادقة باستخدام OAuth 2 كما في السابق، ولكن ستطلب منك أداة gsutil نفسه إدخال بيانات الاعتماد عند استخدامه لأول مرة، ثم سيخزّنها لاستخدامها لاحقًا.

الوصول إلى البيانات آليًا

تتضمن خدمة Google Cloud Storage واجهات برمجة تطبيقات للعديد من لغات البرمجة التي تتيح لك الوصول إلى بياناتك بطريقة آلية. يوضِّح لك النموذج أدناه كيفية إجراء عملية تنزيل بسيطة لأحد ملفات قراءة الكيانات من Google Cloud Storage. تذكَّر أنّه يتم تخزين الملفات المقروءة الخاصة بالكيان فقط في حزمة gdbm-public، وسيتم تخزين الملفات المقروءة الخاصة بالكيان في مجموعات البيانات الخاصة بالشريك والمعلِن.

Java

يستخدم المثال التالي مكتبة برامج Google APIs للغة Java، ما يسهّل الوصول إلى البيانات المحفوظة في Google Cloud Storage. بالإضافة إلى مكتبة عملاء Google APIs العامة الرئيسية، ستحتاج أيضًا إلى تنزيل المكتبة المنفصلة لـ Cloud Storage API.

عليك أولاً إعداد بيانات الاعتماد من أجل استخدامها عند الاتصال بواجهة برمجة التطبيقات للحصول على إذن بالوصول إلى بياناتك. ويتم ذلك من خلال إنشاء عنصر Credential يستخدم عنوان البريد الإلكتروني developer.gserviceaccount.com الخاص بحساب الخدمة على أنّه ServiceAccountId، ويحمِّل أيضًا ملف المفتاح الخاص الذي تم تنزيله من وحدة تحكّم Google API عند إنشاء حساب الخدمة. وسيضمن ذلك توقيع جميع الطلبات المستقبلية لواجهة برمجة التطبيقات باستخدام المفتاح الخاص لحساب الخدمة:

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

...

Credential credential = new GoogleCredential.Builder().setTransport(HTTP_TRANSPORT)
   .setJsonFactory(JSON_FACTORY)
   .setServiceAccountId("[e-mail]")
   .setServiceAccountScopes(StorageScopes.DEVSTORAGE_READ_ONLY)
   .setServiceAccountPrivateKeyFromP12File(new File("...-privatekey.p12"))
   .build();

بعد إنشاء الكائن Credential، يمكنك استخدامه لإنشاء مثيل لكائن Storage جديد يمكنك استخدامه لجميع الطلبات المستقبلية في واجهة برمجة التطبيقات Google Cloud Storage:

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

بعد أن حصلت على عنصر Storage جديد، يمكنك بدء إرسال الطلبات إلى واجهة برمجة التطبيقات. أنت هنا تقدم طلبًا لاسترداد عنصر محدّد 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 بناءً على جزء واجهة برمجة التطبيقات الذي تصل إليه. راجِع القسم المناسب حول اصطلاحات التسمية.

C#

يستخدم المثال التالي مكتبة برامج Google APIs لنظام .NET، ما يجعل الوصول إلى البيانات المحفوظة في Google Cloud Storage بسيطًا وسهلاً.

عليك أولاً إعداد بيانات الاعتماد لاستخدامها عند الاتصال بواجهة برمجة التطبيقات للحصول على إذن للوصول إلى بياناتك. ويتم ذلك من خلال إنشاء عنصر AssertionFlowClient يستخدم عنوان البريد الإلكتروني developer.gserviceaccount.com لحساب الخدمة على أنّه ServiceAccountId، ويحمِّل أيضًا ملف المفتاح الخاص الذي تم تنزيله من وحدة تحكّم Google API عند إنشاء حساب الخدمة.

كلمة مرور المفاتيح الخاصة التي يتم تنزيلها لحسابات الخدمة دائمًا هي notasecret. ولا تحتاج إلى تغيير هذه القيمة.

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

بعد إنشاء الكائن AssertionFlowClient، يمكنك استخدامه لإنشاء مثيل لكائن OAuth2Authenticator جديد يمكنك استخدامه لإنشاء مثيل Storage جديد لجميع الطلبات المستقبلية إلى واجهة برمجة التطبيقات Google Cloud Storage:

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

بعد أن حصلت على عنصر Storage جديد، يمكنك بدء إرسال الطلبات إلى واجهة برمجة التطبيقات. أنت هنا تقدم طلبًا لاسترداد عنصر محدّد، bucketObjectName، من الحزمة bucket. نستخدم فئات مكتبة برامج .NET القياسية لمعالجة تنزيل 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 حسب جزء واجهة برمجة التطبيقات الذي تصل إليه. راجِع القسم المناسب حول اصطلاحات التسمية.

الملحق: نماذج كاملة

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("[e-mail]")
           .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 = "[e-mail]",
                    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;
        }

    }
}