حساب‌های سرویس

حساب سرویس نوعی حساب Google است که برنامه می‌تواند از آن برای دسترسی برنامه‌نویسی‌شده به Google API ازطریق OAuth 2.0 استفاده کند. این کار به مجوز انسانی نیاز ندارد، بلکه از فایل کلیدی استفاده می‌کند که فقط برنامه شما می‌تواند به آن دسترسی داشته باشد.

قبل‌از خواندن مطالب بیشتر درباره حساب‌های سرویس، جایگزین بسیار ساده‌تر و به‌شدت توصیه‌شده پیاده‌سازی جریان برنامه نصب‌شده OAuth 2.0 را درنظر بگیرید. این رویکرد مستلزم آن است که کاربر به‌طور دستی به برنامه اجازه دهد تا ژتون بازآوری تولید کند، اما این کار فقط باید یک‌بار انجام شود زیرا این ژتون‌ها هرگز منقضی نمی‌شوند.

هنوز درحال خواندن هستید؟ بسیارخوب، می‌توانید حساب سرویس را به یکی از روش‌های زیر پیاده‌سازی کنید:

• اگر کاربران شما در دامنه‌های مختلفی قرار دارند، بااستفاده از حساب خدمات به‌عنوان کاربر «مدیر پویش ۳۶۰» پیاده‌سازی کنید. این کار به شما امکان می‌دهد با ایجاد نمایه کاربر جدید در هر حساب و مرتبط کردن همه آن‌ها با یک حساب سرویس، به چندین حساب متعلق به آژانس‌های مختلف متصل شوید. این روش ترجیحی برای استفاده از حساب‌های سرویس با Campaign Manager 360 است.
• اگر کاربران شما در یک دامنه واحد که متعلق به شما است ساکن هستند، واگذاری در سراسر دامنه را اجرا کنید. در این حالت، باید دسترسی سرپرست به دامنه‌ای داشته باشید که در G Suite ثبت شده است. برای دریافت راهنمایی درباره G Suite و / یا پیکربندی دامنه، به صفحه پشتیبانی G Suite مراجعه کنید.

پیش‌نیازها

برای پیاده‌سازی حساب خدمات به‌عنوان کاربر Campaign Manager 360، برگه کاربر Campaign Manager 360 را انتخاب کنید. برای پیاده‌سازی واگذاری در سراسر دامنه، برگه واگذاری را در زیر انتخاب کنید.

کاربر Campaign Manager 360

باید به حساب Campaign Manager 360 با دسترسی فعال‌شده به میانای برنامه‌سازی کاربردی دسترسی داشته باشید.

واگذاری مدیریت

1. باید به حساب Campaign Manager 360 با دسترسی API فعال‌شده دسترسی داشته باشید.
2. باید دسترسی سرپرست به دامنه‌ای داشته باشید که در G Suite ثبت شده باشد.
3. باید نمایه کاربر Campaign Manager 360 داشته باشید که به یک یا چند حساب تحت دامنه ثبت‌شده G Suite شما پیوند شده باشد. از نمایه‌های کاربری که به حساب‌های تحت دامنه‌های دیگر (مثلاً gmail.com) پیوند شده‌اند نمی‌توان استفاده کرد.

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

برای پیاده‌سازی بااستفاده از حساب خدمات به‌عنوان کاربر Campaign Manager 360، برگه کاربر Campaign Manager 360 را انتخاب کنید. برای پیاده‌سازی واگذاری در سراسر دامنه، برگه واگذاری را در زیر انتخاب کنید.

کاربر Campaign Manager 360

1. کلید حساب سرویس را در «کنسول Google API» تولید کنید.
   
   احتیاط: محافظت از فایل کلیدی که به حساب سرویس اجازه دسترسی به سرویس‌های Google را می‌دهد که برای آن‌ها مجاز شده است، مهم است.
2. نمایه کاربر Campaign Manager 360 را با ایمیل حساب سرویس به‌دست‌آمده در مرحله قبلی مرتبط کنید، همان‌طور که در مقاله مرکز راهنمایی مدیریت دسترسی کاربر توضیح داده شده است.
3. جریان OAuth 2.0 سرور به سرور را بااستفاده از حساب خدمات جدیدی که ایجاد کرده‌اید در برنامه‌تان پیاده‌سازی کنید. برای اطلاعات بیشتر، بخش نمونه‌ها را ببینید.

واگذاری

1. کلید حساب سرویس را در «کنسول Google API» تولید کنید.
   
   احتیاط: محافظت از فایل کلیدی که به حساب سرویس اجازه دسترسی به سرویس‌های Google را می‌دهد که برای آن‌ها مجاز شده است، مهم است. این موضوع به‌ویژه برای جریان واگذاری در سراسر دامنه صادق است، زیرا کنترل سطح دامنه G Suite به حساب سرویس این امکان را می‌دهد که خود را به‌جای هر کاربری در دامنه جا بزند. همچنین بهتر است به حساب‌های سرویس اجازه دهید هرکدام فقط به یک Google API دسترسی داشته باشند (بااستفاده از فیلد «محدوده» که در مرحله بعد شرح داده شده است). این یک اقدام پیشگیرانه برای کاهش مقدار داده‌هایی است که مهاجم می‌تواند درصورت لو رفتن فایل کلید حساب سرویس به آن‌ها دسترسی پیدا کند.
2. اختیار سراسری دامنه را به این حساب سرویس واگذار کنید تا بتواند خود را به‌جای کاربران در دامنه‌تان جا بزند. وقتی درخواست شد، دامنه‌های API زیر را ارائه دهید:
   

   حوزه	معنی
   https://www.googleapis.com/auth/dfatrafficking	دسترسی خواندن/ نوشتن به ارائه آگهی Campaign Manager 360.
   https://www.googleapis.com/auth/dfareporting	دسترسی خواندن/ نوشتن به گزارش‌دهی Campaign Manager 360.
   https://www.googleapis.com/auth/ddmconversions	دسترسی خواندن/نوشتن به تبدیل‌های آفلاین Campaign Manager 360.

3. جریان OAuth 2.0 سرور به سرور را بااستفاده از حساب خدمات جدیدی که ایجاد کرده‌اید در برنامه‌تان پیاده‌سازی کنید. برای اطلاعات بیشتر، بخش نمونه‌ها را ببینید. به‌یاد داشته باشید که باید حسابی را برای جعل هویت ارائه دهید و این حساب باید متعلق به دامنه‌ای باشد که حساب سرویس شما در مرحله قبل برای آن اختیار در سطح دامنه دریافت کرده است.

برای دریافت راهنمایی درباره G Suite و / یا پیکربندی دامنه، به صفحه پشتیبانی G Suite مراجعه کنید.

مثال‌ها

C#‎

/*
 * Copyright 2015 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 Google.Apis.Auth.OAuth2;
using Google.Apis.Dfareporting.v5;
using Google.Apis.Dfareporting.v5.Data;
using Google.Apis.Json;
using Google.Apis.Services;
using System;
using System.Collections.Generic;
using System.IO;

namespace DfaReporting.Samples {
  /// <summary>
  /// This example demonstrates how to authenticate and make a basic request using a service
  /// account.
  /// </summary>
  class AuthenticateUsingServiceAccount : SampleBase {
    /// <summary>
    /// The OAuth 2.0 scopes to request.
    /// </summary>
    private static readonly IEnumerable<string> OAuthScopes = new[] {
      DfareportingService.Scope.Dfareporting
    };

    /// <summary>
    /// Returns a description about the code example.
    /// </summary>
    public override string Description {
      get {
        return "This example demonstrates how to authenticate and make a basic request" +
               " using a service account.\n";
      }
    }

    /// <summary>
    /// Main method, to run this code example as a standalone application.
    /// </summary>
    /// <param name="args">The command line arguments.</param>
    public static void Main(string[] args) {
      SampleBase codeExample = new AuthenticateUsingServiceAccount();
      Console.WriteLine(codeExample.Description);
      codeExample.Run(null);
    }

    /// <summary>
    /// Run the code example.
    /// </summary>
    /// <param name="service">Unused</param>
    public override void Run(DfareportingService service) {
      string pathToJsonFile = _T("ENTER_PATH_TO_JSON_FILE_HERE");

      // An optional Google account email to impersonate. Only applicable to service accounts which
      // have enabled domain-wide delegation and wish to make API requests on behalf of an account
      // within their domain. Setting this field will not allow you to impersonate a user from a
      // domain you don't own (e.g., gmail.com).
      string emailToImpersonate = _T("");

      // Build service account credential.
      ICredential credential =
          getServiceAccountCredential(pathToJsonFile, emailToImpersonate);

      // Create a Dfareporting service object.
      //
      // Note: application name should be replaced with a value that identifies your application.
      service = new DfareportingService(
          new BaseClientService.Initializer {
            HttpClientInitializer = credential,
            ApplicationName = "C# service account sample"
          }
      );

      // Retrieve and print all user profiles for the current authorized user.
      UserProfileList profiles = service.UserProfiles.List().Execute();

      foreach (UserProfile profile in profiles.Items) {
        Console.WriteLine("Found user profile with ID {0} and name \"{1}\".",
            profile.ProfileId, profile.UserName);
      }
    }

    private ICredential getServiceAccountCredential(String pathToJsonFile,
        String emailToImpersonate) {
      GoogleCredential credential;
      using (Stream json = new FileStream(pathToJsonFile, FileMode.Open, FileAccess.Read)) {
        credential = CredentialFactory.FromStream<ServiceAccountCredential>(json)
            .ToGoogleCredential()
            .CreateScoped(OAuthScopes);
      }

      if (!String.IsNullOrEmpty(emailToImpersonate)) {
        credential = credential.CreateWithUser(emailToImpersonate);
      }

      return credential;
    }
  }
}

جاوا

// Copyright 2014 Google Inc. All Rights Reserved.
//
// 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.api.services.samples.dfareporting.auth;

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.dfareporting.Dfareporting;
import com.google.api.services.dfareporting.DfareportingScopes;
import com.google.api.services.dfareporting.model.UserProfileList;
import com.google.common.base.Strings;
import com.google.common.collect.ImmutableSet;
import java.io.FileInputStream;

/**
 * This example demonstrates how to authenticate and make a basic request using a service account.
 */
public class AuthenticateUsingServiceAccount {
  private static final String PATH_TO_JSON_FILE = "ENTER_PATH_TO_JSON_FILE_HERE";

  /**
   * An optional Google account email to impersonate. Only applicable to service accounts which have
   * enabled domain-wide delegation and wish to make API requests on behalf of an account within
   * their domain. Setting this field will not allow you to impersonate a user from a domain you
   * don't own (e.g., gmail.com).
   */
  private static final String EMAIL_TO_IMPERSONATE = "";

  // The OAuth 2.0 scopes to request.
  private static final ImmutableSet<String> OAUTH_SCOPES =
      ImmutableSet.of(DfareportingScopes.DFAREPORTING);

  private static Credential getServiceAccountCredential(
      String pathToJsonFile, String emailToImpersonate) throws Exception {
    // Generate a credential object from the specified JSON file.
    GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream(pathToJsonFile));

    // Update the credential object with appropriate scopes and impersonation info (if applicable).
    if (Strings.isNullOrEmpty(emailToImpersonate)) {
      credential = credential.createScoped(OAUTH_SCOPES);
    } else {
      credential =
          new GoogleCredential.Builder()
              .setTransport(credential.getTransport())
              .setJsonFactory(credential.getJsonFactory())
              .setServiceAccountId(credential.getServiceAccountId())
              .setServiceAccountPrivateKey(credential.getServiceAccountPrivateKey())
              .setServiceAccountScopes(OAUTH_SCOPES)
              // Set the email of the user you are impersonating (this can be yourself).
              .setServiceAccountUser(emailToImpersonate)
              .build();
    }

    return credential;
  }

  public static void runExample(Dfareporting reporting) throws Exception {
    // Retrieve and print all user profiles for the current authorized user.
    UserProfileList profiles = reporting.userProfiles().list().execute();
    for (int i = 0; i < profiles.getItems().size(); i++) {
      System.out.printf("%d) %s%n", i + 1, profiles.getItems().get(i).getUserName());
    }
  }

  public static void main(String[] args) throws Exception {
    // Build service account credential.
    Credential credential = getServiceAccountCredential(PATH_TO_JSON_FILE, EMAIL_TO_IMPERSONATE);

    // Create a Dfareporting client instance.
    //
    // Note: application name below should be replaced with a value that identifies your
    // application. Suggested format is "MyCompany-ProductName/Version.MinorVersion".
    Dfareporting reporting =
        new Dfareporting.Builder(credential.getTransport(), credential.getJsonFactory(), credential)
            .setApplicationName("dfareporting-java-service-acct-sample")
            .build();

    runExample(reporting);
  }
}

PHP

<?php
/*
 * Copyright 2017 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.
 */

require_once dirname(__DIR__) . '/vendor/autoload.php';

/**
 * This example demonstrates how to authenticate and make a basic request using
 * a service account.
 *
 * This example is written to be run as a command line application, not as a
 * webpage. An optional Google account email to impersonate may be specified as
 * follows:
 *
 *     AuthenticateUsingServiceAccount.php /path/to/client_secrets.json <email>
 *
 * This optional flag only applies to service accounts which have domain-wide
 * delegation enabled and wish to make API requests on behalf of an account
 * within that domain. Using this flag will not allow you to impersonate a user
 * from a domain that you don't own (e.g., gmail.com).
 */
class AuthenticateUsingServiceAccount
{
    // The OAuth 2.0 scopes to request.
    private static $OAUTH_SCOPES = [
        Google_Service_Dfareporting::DFAREPORTING
    ];

    public function run($pathToJsonFile, $email = null)
    {
        // Create an authenticated client object.
        $client = $this->createAuthenticatedClient($pathToJsonFile, $email);

        // Create a Dfareporting service object.
        $service = new Google_Service_Dfareporting($client);

        $this->getUserProfiles($service);
    }

    private function createAuthenticatedClient($pathToJsonFile, $email)
    {
        // Create a Google_Client instance.
        //
        // Note: application name should be replaced with a value that identifies
        // your application. Suggested format is "MyCompany-ProductName".
        $client = new Google_Client();
        $client->setApplicationName('PHP service account sample');
        $client->setScopes(self::$OAUTH_SCOPES);

        // Load the service account credentials.
        $client->setAuthConfig($pathToJsonFile);

        // Configure impersonation (if applicable).
        if (!is_null($email)) {
            $client->setSubject($email);
        }

        return $client;
    }

    private function getUserProfiles($service)
    {
        // Retrieve and print all user profiles for the current authorized user.
        $result = $service->userProfiles->listUserProfiles();
        foreach ($result['items'] as $userProfile) {
            printf(
                "User profile \"%s\" (ID: %d) found for account %d.\n",
                $userProfile->getUserName(),
                $userProfile->getProfileId(),
                $userProfile->getAccountId()
            );
        }
    }
}

if ($argc < 2 || $argc >= 4) {
    printf(
        "Usage: %s /path/to/client_secrets.json [email_to_impersonate]\n",
        $argv[0]
    );
} else {
    $sample = new AuthenticateUsingServiceAccount();

    if ($argc == 2) {
        $sample->run($argv[1]);
    } else {
        $sample->run($argv[1], $argv[2]);
    }
}

Python

#!/usr/bin/python
#
# Copyright 2015 Google Inc. All Rights Reserved.
#
# 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.

"""This example demonstrates how to authenticate using a service account.

An optional Google account email to impersonate may be specified as follows:
    authenticate_using_service_account.py <path_to_json_file> -i <email>

This optional flag only applies to service accounts which have domain-wide
delegation enabled and wish to make API requests on behalf of an account
within that domain. Using this flag will not allow you to impersonate a
user from a domain you don't own (e.g., gmail.com).
"""

import argparse
import sys

from googleapiclient import discovery
import httplib2
from oauth2client import client
from oauth2client import tools
from oauth2client.service_account import ServiceAccountCredentials

# Declare command-line flags.
argparser = argparse.ArgumentParser(add_help=False)
argparser.add_argument(
    'path_to_service_account_json_file',
    help='Path to the service account JSON file to use for authenticating.')
argparser.add_argument(
    '-i',
    '--impersonation_email',
    help='Google account email to impersonate.')

# The OAuth 2.0 scopes to request.
OAUTH_SCOPES = ['https://www.googleapis.com/auth/dfareporting']


def main(argv):
  # Retrieve command line arguments.
  parser = argparse.ArgumentParser(
      description=__doc__,
      formatter_class=argparse.RawDescriptionHelpFormatter,
      parents=[tools.argparser, argparser])
  flags = parser.parse_args(argv[1:])

  # Authenticate using the supplied service account credentials
  http = authenticate_using_service_account(
      flags.path_to_service_account_json_file,
      flags.impersonation_email)

  # Construct a service object via the discovery service.
  service = discovery.build('dfareporting', 'v5', http=http)

  try:
    # Construct the request.
    request = service.userProfiles().list()

    # Execute request and print response.
    response = request.execute()

    for profile in response['items']:
      print('Found user profile with ID %s and user name "%s".' %
            (profile['profileId'], profile['userName']))

  except client.AccessTokenRefreshError:
    print('The credentials have been revoked or expired, please re-run the '
          'application to re-authorize')


def authenticate_using_service_account(path_to_service_account_json_file,
                                       impersonation_email):
  """Authorizes an httplib2.Http instance using service account credentials."""
  # Load the service account credentials from the specified JSON keyfile.
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      path_to_service_account_json_file,
      scopes=OAUTH_SCOPES)

  # Configure impersonation (if applicable).
  if impersonation_email:
    credentials = credentials.create_delegated(impersonation_email)

  # Use the credentials to authorize an httplib2.Http instance.
  http = credentials.authorize(httplib2.Http())

  return http


if __name__ == '__main__':
  main(sys.argv)

Ruby

#!/usr/bin/env ruby

#
# Copyright:: Copyright 2016, Google Inc. All Rights Reserved.
#
# License:: 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.
#
# This example demonstrates how to authenticate using a service account.
#
# An optional Google account email to impersonate may be specified as follows:
#    authenticate_using_service_account.rb <path_to_json_file> --i <email>
#
# This optional flag only applies to service accounts which have domain-wide
# delegation enabled and wish to make API requests on behalf of an account
# within that domain. Using this flag will not allow you to impersonate a
# user from a domain you don't own (e.g., gmail.com).

require 'google/apis/dfareporting_v5'
require 'googleauth'
require 'optparse'

API_NAMESPACE = Google::Apis::DfareportingV5

def authenticate_using_service_account(path_to_json_file, impersonation_email)
  # Create a Dfareporting service object.
  #
  # Note: application name should be replaced with a value that identifies
  # your application. Suggested format is "MyCompany-ProductName".
  service = API_NAMESPACE::DfareportingService.new
  service.client_options.application_name = 'Ruby service account sample'
  service.client_options.application_version = '1.0.0'

  # Generate an authorization object from the specified JSON file.
  File.open(path_to_json_file, 'r+') do |json|
    service.authorization =
      Google::Auth::ServiceAccountCredentials.make_creds(
        json_key_io: json,
        scope: [API_NAMESPACE::AUTH_DFAREPORTING]
      )
  end

  # Configure impersonation (if applicable).
  service.authorization.sub = impersonation_email unless
    impersonation_email.nil?

  service
end

def get_userprofiles(service)
  # Get all user profiles.
  result = service.list_user_profiles

  # Display results.
  result.items.each do |profile|
    puts format(
      'User profile with ID %d and name "%s" was found for account %d.',
      profile.profile_id, profile.user_name, profile.account_id
    )
  end
end

if $PROGRAM_NAME == __FILE__
  # Retrieve command line arguments.
  impersonation_email = nil
  optparse = OptionParser.new do |opts|
    opts.banner = format('Usage: %s path_to_json_file [options]', $PROGRAM_NAME)
    opts.on_tail('-i', '--impersonate EMAIL',
      'Google account email to impersonate') do |email|
      impersonation_email = email
    end
  end
  optparse.parse!

  if ARGV.empty?
    puts optparse
    exit(-1)
  end

  # Authenticate and initialize API service using service account.
  service = authenticate_using_service_account(ARGV.shift, impersonation_email)

  get_userprofiles(service)
end