با Ads Data Hub API شروع کنید

این راهنما نحوه شروع نوشتن برنامه‌هایی را توضیح می‌دهد که از API REST مربوط به Ads Data Hub برای تعامل با Ads Data Hub استفاده می‌کنند. API REST مربوط به Ads Data Hub به شما امکان می‌دهد مشتریان Ads Data Hub مرتبط با حساب گوگل خود را مشاهده کنید، پرس‌وجو ایجاد کنید و پرس‌وجوها را اجرا کنید.

راه‌اندازی

قبل از استفاده از Ads Data Hub API، چند مرحله وجود دارد که باید انجام دهید:

1. مطمئن شوید که به کاربری که API را فعال می‌کند، مجوز serviceusage.services.enable در پروژه Google Cloud اعطا شده باشد. کاربری که مجوز serviceusage.services.enable را دارد، باید برای دسترسی به API نیز در لیست مجاز قرار گرفته باشد.
2. API مربوط به Ads Data Hub را در پروژه Google Cloud که در آن اعتبارنامه‌های کلاینت یا حساب سرویس ایجاد شده‌اند، فعال کنید. برای فعال کردن API مربوط به Ads Data Hub برای یک پروژه با استفاده از کنسول:
   1. به کتابخانه API کنسول ابری بروید.
   2. پروژه‌ای را که می‌خواهید استفاده کنید از لیست پروژه‌ها انتخاب کنید.
   3. عبارت «API مرکز داده‌های تبلیغات» را جستجو کنید.
   4. در صفحه API، روی فعال کردن (ENABLE) کلیک کنید.
3. مدیریت مجوزها:
   1. آدرس ایمیل یا حساب کاربری سرویس که برای ایجاد اعتبارنامه‌ها استفاده می‌شود، باید با مجوزهای مناسب به Ads Data Hub اضافه شود. برای یک حساب کاربری سرویس، این آدرس ایمیل حساب کاربری سرویس است. برای OAuth، این آدرس ایمیل کاربر است. این تضمین می‌کند که حساب کاربری سرویس یا حساب کاربری نهایی، مجوز اجرای کوئری‌ها در Ads Data Hub را دارد.
4. (توصیه می‌شود) یک کتابخانه کلاینت API گوگل نصب کنید:
   1. کتابخانه‌های کلاینت Google API به چندین زبان محبوب در دسترس هستند و به شما امکان می‌دهند با بسیاری از APIهای Google کار کنید. اگرچه این مورد الزامی نیست، اما کتابخانه‌های کلاینت میزان کدی را که باید بنویسید کاهش می‌دهند و راه‌اندازی احراز هویت را ساده‌تر می‌کنند.

کتابخانه مشتری	نمونه‌های مرکز داده تبلیغات
کتابخانه کلاینت API گوگل برای جاوا	جاوا
کتابخانه کلاینت API گوگل برای پایتون

احراز هویت و مجوز دادن

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

حساب کاربری سرویس OAuth 2.0

راه‌اندازی OAuth 2.0

این API هم از جریان برنامه نصب‌شده و هم از جریان برنامه وب پشتیبانی می‌کند، اما برای این مثال، جریان برنامه نصب‌شده را بررسی خواهیم کرد.

1. به کنسول Google API بروید و به پروژه ادمین خود بروید.
2. تأیید کنید که API مربوط به Ads Data Hub برای پروژه شما فعال شده است.
   1. اگر اینطور نیست، برای فعال کردن آن روی + فعال کردن APIها و خدمات کلیک کنید.
3. در نوار ناوبری سمت چپ، روی «اعتبارنامه‌ها» کلیک کنید.
4. منوی کشویی «ایجاد اعتبارنامه‌ها» را باز کنید و «شناسه کلاینت OAuth» را انتخاب کنید. در صفحه بعد:
   1. سایر را انتخاب کنید.
   2. در صورت تمایل، برای کلاینت یک نام تعیین کنید.
   3. روی ایجاد کلیک کنید.
5. روی نماد دانلود در کنار اعتبارنامه‌هایی که تازه ایجاد کرده‌اید کلیک کنید.

کلید API خود را دریافت کنید

کلید API شما (که با نام کلید توسعه‌دهنده نیز شناخته می‌شود) برای احراز هویت در نمونه کد پایتون زیر استفاده می‌شود. برای دریافت کلید API خود:

1. به صفحه «اعتبارنامه‌ها» در کنسول API بروید
2. مطمئن شوید که پروژه مدیریت شما در منوی کشویی بالای صفحه انتخاب شده است.
3. روی نماد دانلود کنار کلید API خود کلیک کنید.

ارسال نمونه درخواست

پایتون

"""This sample shows how to retrieve all accounts associated with the user.

For the program to execute successfully, ensure that you run it using Python 3.
"""
import json
from google_auth_oauthlib import flow
from googleapiclient.discovery import build

appflow = flow.InstalledAppFlow.from_client_secrets_file(
    # Replace client_secrets.json with your own client secret file.
    'client_secrets.json',
    scopes=['https://www.googleapis.com/auth/adsdatahub'])
appflow.run_local_server()
credentials = appflow.credentials
developer_key = input('Developer key: ').strip()
# For versions of the Google API Python client library prior to 2.0, the
# `static_discovery` parameter below should be removed.
service = build('AdsDataHub', 'v1', credentials=credentials,
                developerKey=developer_key, static_discovery=False)


def pprint(x):
  print(json.dumps(x, sort_keys=True, indent=4))


adh_account_id = input('ADH account ID (e.g. "customers/123456789"): ').strip()
pprint(service.customers().analysisQueries().list(parent
                                                  =adh_account_id).execute())

      

جاوا

/*
 * Copyright (c) 2019 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.api.services.samples.adsdatahub.cmdline;

import com.google.api.services.adsdatahub.v1.AdsDataHub;
import com.google.api.services.adsdatahub.v1.model.Customer;
import com.google.api.services.adsdatahub.v1.model.ListCustomersResponse;
import java.io.IOException;
import java.util.List;

/**
 * This sample illustrates how to retrieve all accounts associated to the user.
 *
 * <p>See the <a href="customers.list reference
 * documentation">https://developers.google.com/ads-data-hub/reference/rest/v1/customers/list</a>
 * for more details.
 */
public class ListCustomers extends BaseSample {

  @Override
  public String getName() {
    return "List customers";
  }

  @Override
  public String getDescription() {
    return "Lists customers associated with the authorized user";
  }

  @Override
  public void execute(AdsDataHub client) throws IOException {
    String pageToken = null;
    boolean noData = true;

    System.out.println("========================================");
    System.out.printf("Listing of customers associated with the authorized user:\n");
    System.out.println("========================================");

    do {
      ListCustomersResponse response = client.customers().list().setPageToken(pageToken).execute();
      pageToken = response.getNextPageToken();
      List<Customer> customers = response.getCustomers();

      if (customers != null && customers.size() > 0) {
        noData = false;
        for (Customer customer : customers) {
          System.out.printf("* Customer id: %d\n", customer.getCustomerId());
          System.out.printf("\tCustomer name: %s\n", customer.getDisplayName());
        }
      }
    } while (pageToken != null);

    if (noData) {
      System.out.println("No customers were found associated with the authorized user.");
    }
  }
}

      

مراحل بعدی

• برای مثال‌هایی از پرس‌وجوهایی که می‌توانید با API REST هاب داده‌ی ادز ایجاد و اجرا کنید، به پرس‌وجوهای نمونه در ادز دیتا هاب مراجعه کنید.
• برای آشنایی با API و سفارشی‌سازی آن برای مورد استفاده خود، نمونه‌ها را بسط دهید. سپس سعی کنید:
  • وضعیت عملیات پرس و جوی نظرسنجی.
  • برای بازیابی نتایج پرس‌وجوی تکمیل‌شده، از یک کتابخانه کلاینت BigQuery استفاده کنید.
• اگر در مورد API سؤالی یا نظری دارید، با پشتیبانی ADH تماس بگیرید.