תחילת השימוש ב-Ads Data Hub API

במדריך הזה מוסבר איך מתחילים לכתוב אפליקציות שמשתמשות ב-API בארכיטקטורת REST של Ads Data Hub כדי ליצור אינטראקציה עם Ads Data Hub. ‫Ads Data Hub API בארכיטקטורת REST מאפשר לכם לראות לקוחות של Ads Data Hub שמשויכים לחשבון Google שלכם, ליצור שאילתות ולהריץ אותן.

הגדרה

לפני שמשתמשים ב-API של Ads Data Hub, צריך לבצע כמה שלבים:

1. חשוב לוודא שלמשתמש שמפעיל את ה-API יש serviceusage.services.enableהרשאה בפרויקט ב-Google Cloud. גם המשתמש עם הרשאת serviceusage.services.enable צריך להיכלל ברשימת ההיתרים כדי לקבל גישה ל-API.
2. מפעילים את Ads Data Hub API בפרויקט בענן של Google שבו נוצרו פרטי הכניסה של הלקוח או חשבון השירות. כדי להפעיל את Ads Data Hub API בפרויקט באמצעות המסוף:
   1. עוברים אל ספריית ה-API של Cloud Console.
   2. בוחרים את הפרויקט שרוצים להשתמש בו מתוך רשימת הפרויקטים.
   3. מחפשים את 'Ads Data Hub API'.
   4. בדף ה-API, לוחצים על הפעלה.
3. ניהול הרשאות:
   1. צריך להוסיף ל-Ads Data Hub את כתובת האימייל או חשבון השירות ששימשו ליצירת פרטי הכניסה, עם ההרשאות המתאימות. בחשבון שירות, זו כתובת האימייל בחשבון. ב-OAuth, זוהי כתובת האימייל של המשתמש. כך מוודאים שלחשבון השירות או לחשבון של משתמש הקצה יש הרשאה להריץ שאילתות ב-Ads Data Hub.
4. (מומלץ) מתקינים ספריית לקוח של Google API:
   1. ספריות הלקוח של Google API זמינות בכמה שפות פופולריות, ומאפשרות לכם לעבוד עם הרבה ממשקי Google API. השימוש בספריות הלקוח לא חובה, אבל הוא מפחית את כמות הקוד שצריך לכתוב ומפשט את הגדרת האימות.

ספריית לקוח	דוגמאות לשימוש ב-Ads Data Hub
‫Google API Client Library for Java	Java
Google API Client Library for Python

אימות והרשאה

ל-Ads Data Hub API יש גישה לנתונים בחשבון הלקוח שלכם ב-Ads Data Hub, והוא יכול לשנות אותם. לכן, הוא צריך לוודא שאתם משתמשים מורשים. לכן, לפני שמתחילים ליצור אינטראקציה עם Ads Data Hub API, צריך לעבור תהליך הרשאה. תהליך הרשאה מספק לכם את ההרשאות הנדרשות כדי ליצור אינטראקציה עם ה-API. אפשר לבצע אימות באמצעות OAuth 2.0 או חשבון שירות.

OAuth 2.0 חשבון שירות

הגדרת OAuth 2.0

ה-API תומך גם בתהליכי עבודה של אפליקציות מותקנות וגם בתהליכי עבודה של אפליקציות אינטרנט, אבל בדוגמה הזו נסביר על תהליך העבודה של אפליקציות מותקנות.

1. עוברים אל Google API console ואל פרויקט האדמין.
2. מוודאים ש-Ads Data Hub API מופעל בפרויקט.
   1. אם הוא לא מופיע, לוחצים על + Enable APIs and services (הפעלת ממשקי API ושירותים) כדי להפעיל אותו.
3. בתפריט הניווט הימני, לוחצים על Credentials (פרטי כניסה).
4. פותחים את התפריט הנפתח Create credentials (יצירת פרטי כניסה) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth). בדף הבא:
   1. בוחרים באפשרות 'אחר'.
   2. אם רוצים, נותנים ללקוח שם.
   3. לוחצים על 'יצירה'.
5. לוחצים על סמל ההורדה לצד פרטי הכניסה שיצרתם.

קבלת מפתח API

מפתח ה-API (שנקרא גם מפתח למפתחים) משמש לאימות בדוגמת הקוד של Python שמופיעה בהמשך. כדי לקבל את מפתח ה-API:

1. עוברים לדף Credentials (פרטי כניסה) במסוף API.
2. מוודאים שהפרויקט שלכם ב-Admin נבחר בתפריט הנפתח שבסרגל הניווט העליון.
3. לוחצים על סמל ההורדה לצד מפתח ה-API.

שליחת בקשה לקבלת דוגמית

Python

"""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())

      

Java

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

      

השלבים הבאים

• במאמר שאילתות לדוגמה ב-Ads Data Hub יש דוגמאות לשאילתות שאפשר ליצור ולהריץ באמצעות Ads Data Hub API בארכיטקטורת REST.
• כדאי להרחיב את הדוגמאות כדי להכיר את ה-API ולהתאים אותו לתרחיש השימוש שלכם. אחר כך מנסים:
  • דגימה של סטטוס פעולת השאילתה.
  • משתמשים בספריית לקוח של BigQuery כדי לאחזר את תוצאות השאילתה שהושלמה.
• אם יש לכם שאלות או משוב לגבי ה-API, אתם יכולים לפנות לתמיכה של ADH.