דף זה תורגם על ידי Cloud Translation API.

שנתחיל?

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

ב-Ad Manager API נעשה שימוש ב-SOAP. כדי לעזור לכם להתחיל, אנחנו מציעים ספריות לקוח ל-Java , NET , Python , Rup ו-Ruby. כדי להגיש את בקשת ה-API הראשונה, פועלים לפי השלבים הבאים.

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

חשוב לרשום את קוד הרשת. תוכלו למצוא אותו בכתובת ה-URL כשתתחברו לרשת. לדוגמה, בכתובת ה-URL https://admanager.google.com/1234#home, 1234 הוא קוד הרשת.

יצירת פרטי כניסה לאימות

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

פותחים את דף פרטי הכניסה במסוף Google API.
בתפריט Project, בוחרים באפשרות Create Project, נותנים שם לפרויקט, ואם רוצים גם עורכים את מזהה הפרויקט שסופק. לוחצים על Create.
בדף Credentials, בוחרים Create credentials ואז באפשרות Service account key.
בוחרים באפשרות New Service account (חשבון שירות חדש) ובוחרים באפשרות JSON כסוג המפתח.
לוחצים על יצירה כדי להוריד קובץ שמכיל מפתח פרטי.

הגדרה של רשת Ad Manager

נכנסים ל-Google Ad Manager.
בסרגל הצד, לוחצים על מנהל מערכת > הגדרות גלובליות.
בקטע General settings (הגדרות כלליות) > Api access (גישה לממשק ה-API), לוחצים על פס ההזזה Enabled (מופעלת).
לוחצים על הלחצן שמירה בחלק התחתון של הדף.

הגדרת הלקוח

מורידים אחת מספריות הלקוח של Ad Manager. הספריות כוללות פונקציות wrapper ותכונות שהופכות את הפיתוח של האפליקציות לקל ומהיר יותר.

בכרטיסיות הבאות תמצאו מדריכים למתחילים בכל אחת מהשפות שיש בהן ספריית לקוחות.

Java

הדוגמה הבאה ממחישה איך משתמשים בספריית הלקוח של Java. למידע מפורט יותר על השימוש, קראו את הקובץ README בהתפלגות של ספריית הלקוח.

הגדרת פרטי הכניסה

מריצים את הפקודה הבאה במעטפת:

curl https://raw.githubusercontent.com/googleads/googleads-java-lib/main/examples/admanager_axis/src/main/resources/ads.properties -o ~/ads.properties

פותחים את הקובץ ~/ads.properties ומאכלסים את השדות הבאים:

[...]
api.admanager.applicationName=INSERT_APPLICATION_NAME_HERE
api.admanager.jsonKeyFilePath=INSERT_PATH_TO_JSON_KEY_FILE_HERE
api.admanager.networkCode=INSERT_NETWORK_CODE_HERE
[...]

ציון יחסי תלות

יש לערוך את הקובץ pom.xml ולהוסיף את התג הבא לתג dependencies. מספר הגרסה העדכני זמין ב- GitHub.

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>ads-lib</artifactId>
  <version>RELEASE</version>
</dependency>
<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>dfp-axis</artifactId>
  <version>RELEASE</version>
</dependency>

מזינים קוד ושולחים בקשה.

import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.ads.admanager.axis.factory.AdManagerServices;
import com.google.api.ads.admanager.axis.v202305.Network;
import com.google.api.ads.admanager.axis.v202305.NetworkServiceInterface;
import com.google.api.ads.admanager.lib.client.AdManagerSession;
import com.google.api.client.auth.oauth2.Credential;

public class App {
  public static void main(String[] args) throws Exception {
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.AD_MANAGER)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdManagerSession.
    AdManagerSession session = new AdManagerSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    // Construct a Google Ad Manager service factory, which can only be used once per
    // thread, but should be reused as much as possible.
    AdManagerServices adManagerServices = new AdManagerServices();

    // Retrieve the appropriate service
    NetworkServiceInterface networkService = adManagerServices.get(session,
        NetworkServiceInterface.class);

    // Make a request
    Network network = networkService.getCurrentNetwork();

    System.out.printf("Current network has network code '%s' and display" +
        " name '%s'.%n", network.getNetworkCode(), network.getDisplayName());
  }
}

הצגת הקוד ב-GitHub

Python

הנה דוגמה בסיסית שמראה איך להשתמש בספריית הלקוח של Python. ספריית הלקוח Python תומכת ב-Python בגרסה 3.6 ואילך. למידע מפורט יותר על השימוש, לחצו על הקובץ README בהפצה של ספריית הלקוח.

מתקינים את הספרייה ומגדירים את פרטי הכניסה.

מריצים את הפקודות הבאות במעטפת:

pip install googleads
curl https://raw.githubusercontent.com/googleads/googleads-python-lib/main/googleads.yaml \
     -o ~/googleads.yaml

מגדירים קובץ ~/googleads.yaml.

ממלאים את השדות הבאים:

ad_manager:
  application_name: INSERT_APPLICATION_NAME_HERE
  network_code: INSERT_NETWORK_CODE_HERE
  path_to_private_key_file: INSERT_PATH_TO_FILE_HERE

מריצים קוד ושולחים בקשה.

# Import the library.
from googleads import ad_manager

# Initialize a client object, by default uses the credentials in ~/googleads.yaml.
client = ad_manager.AdManagerClient.LoadFromStorage()

# Initialize a service.
network_service = client.GetService('NetworkService', version='v202305')

# Make a request.
current_network = network_service.getCurrentNetwork()

print("Current network has network code '%s' and display name '%s'." %
        (current_network['networkCode'], current_network['displayName']))

הצגת הקוד ב-GitHub

PHP‏

הנה דוגמה בסיסית שמראה איך להשתמש בספריית הלקוח של PHP.

מתקינים את הספרייה ומגדירים את פרטי הכניסה.
מריצים את הפקודות הבאות במעטפת כדי להתקין את ספריית הלקוח ומורידים את קובץ ה-adsapi_php.ini אל ספריית הבית:
```
composer require googleads/googleads-php-lib
curl https://raw.githubusercontent.com/googleads/googleads-php-lib/main/examples/AdManager/adsapi_php.ini -o ~/adsapi_php.ini
```

מגדירים קובץ ~/adsapi_php.ini.

ממלאים את השדות הבאים:

[AD_MANAGER]
networkCode = "INSERT_NETWORK_CODE_HERE"
applicationName = "INSERT_APPLICATION_NAME_HERE"

[OAUTH2]
jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
scopes = "https://www.googleapis.com/auth/dfp"

מריצים חלק מהקוד ושולחים בקשה.

יש להריץ את הקוד לדוגמה הזה משורת הפקודה, ולא מדפדפן. הקובץ שמכיל את הקוד הזה חייב להימצא בספריית הבסיס של ספריית הפרויקטים, שבה רצה הפקודה composer require.

<?php
require 'vendor/autoload.php';
use Google\AdsApi\AdManager\AdManagerSession;
use Google\AdsApi\AdManager\AdManagerSessionBuilder;
use Google\AdsApi\AdManager\v202305\ApiException;
use Google\AdsApi\AdManager\v202305\ServiceFactory;
use Google\AdsApi\Common\OAuth2TokenBuilder;

// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();
// Construct an API session configured from a properties file and the OAuth2
// credentials above.
$session = (new AdManagerSessionBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

// Get a service.
$serviceFactory = new ServiceFactory();
$networkService = $serviceFactory->createNetworkService($session);

// Make a request
$network = $networkService->getCurrentNetwork();
printf(
    "Network with code %d and display name '%s' was found.\n",
    $network->getNetworkCode(),
    $network->getDisplayName()
);

הצגת הקוד ב-GitHub

‎.NET

הנה דוגמה בסיסית שמראה איך להשתמש בספריית הלקוח עם הסיומת.NET

יצירת פרויקט חדש
פותחים את Visual Studio ויוצרים פרויקט חדש (כלומר, אפליקציית Console).
הוספה של הפניות חובה לספרייה לפרויקט
מוסיפים תלות בתקן Google.Dfp.
הגדרה של App.config
מעתיקים את src\App.config לספריית הפרויקט ומוסיפים אותו לפרויקט. אם לאפליקציה יש קובץ App.config משלה, אפשר להעתיק את הצמתים הבאים ל-App.config:
- הגדרה/AdManagerApi
- configuration/configsections/section[name="AdManagerApi"]
- configuration/system.net

הגדרת פרטי הכניסה

פותחים את App.config ועורכים את המפתחות הבאים:

<add key="ApplicationName" value="INSERT_YOUR_APPLICATION_NAME_HERE" />
<add key="NetworkCode" value="INSERT_YOUR_NETWORK_CODE_HERE" />
<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="INSERT_OAUTH2_SECRETS_JSON_FILE_PATH_HERE" />

ביצוע שיחה לספרייה

אפשר לקרוא לספרייה כפי שמוצג בקטע הקוד הבא של C#

הצגת הקוד ב-GitHub

AdManagerUser user = new AdManagerUser();
      using (InventoryService inventoryService = user.GetService<InventoryService>())
            {
                // Create a statement to select ad units.
                int pageSize = StatementBuilder.SUGGESTED_PAGE_LIMIT;
                StatementBuilder statementBuilder =
                    new StatementBuilder().OrderBy("id ASC").Limit(pageSize);

                // Retrieve a small amount of ad units at a time, paging through until all
                // ad units have been retrieved.
                int totalResultSetSize = 0;
                do
                {
                    AdUnitPage page =
                        inventoryService.getAdUnitsByStatement(statementBuilder.ToStatement());

                    // Print out some information for each ad unit.
                    if (page.results != null)
                    {
                        totalResultSetSize = page.totalResultSetSize;
                        int i = page.startIndex;
                        foreach (AdUnit adUnit in page.results)
                        {
                            Console.WriteLine(
                                "{0}) Ad unit with ID \"{1}\" and name \"{2}\" was found.", i++,
                                adUnit.id, adUnit.name);
                        }
                    }

                    statementBuilder.IncreaseOffsetBy(pageSize);
                } while (statementBuilder.GetOffset() < totalResultSetSize);

                Console.WriteLine("Number of results found: {0}", totalResultSetSize);
            }

אם אתם לא רוצים להגדיר את פרטי הכניסה ב-App.config, תוכלו להיעזר במאמר הזה ב-wiki כדי למצוא דרכים חלופיות לשימוש ב-AdManagerUser. מידע מפורט על השימוש בספריית הלקוח NET .זמין במאמר README . למידע על פיתוח ב-NET .בלי ספריית הלקוח, קראו את המאמר ב-wiki של NoClientLibrary.

Ruby

הדוגמה הבאה ממחישה איך להשתמש בספריית הלקוח של Ruby. ספריית הלקוח של Ruby מחייבת Ruby 2.1 ואילך.

מתקינים את ה-Ruby gem ומקבלים את קובץ התצורה.
מריצים את הפקודות הבאות במעטפת:
```
gem install google-dfp-api
curl https://raw.githubusercontent.com/googleads/google-api-ads-ruby/main/ad_manager_api/ad_manager_api.yml -o ~/ad_manager_api.yml
```
אם תיתקלו בשגיאה כמו "cannot load such file -- mkmf (LoadError)" בכל שלב במהלך התקנת אבני חן, ייתכן שתצטרכו להתקין ספריות נוספות של פיתוח רובי, כמו ruby-dev, ruby-deble, xcode-select וכו' עבור הסביבה הספציפית שלכם.
הגדרת פרטי הכניסה
לאכלס את שדות החובה בקובץ ~/ad_manager_api.yml. אם עדיין אין לכם קובץ מפתח OAuth2, עליכם לפעול לפי השלבים ליצירת פרטי כניסה של OAuth2.
```
:authentication:
  :oauth2_keyfile: INSERT_PATH_TO_JSON_KEY_FILE_HERE
  :application_name: INSERT_APPLICATION_NAME_HERE
  :network_code: INSERT_NETWORK_CODE_HERE
```

מזינים קוד ושולחים בקשה.

# Import the library.
require 'ad_manager_api'

# Initialize an Ad Manager client instance (uses credentials in ~/ad_manager_api.yml by default).
ad_manager = AdManagerApi::Api.new

# Get a service instance.
network_service = ad_manager.service(:NetworkService, :v202305)

# Make a request.
network = network_service.get_current_network()

puts "The current network is %s (%d)." %
        [network[:display_name], network[:network_code]]

הצגת הקוד ב-GitHub

הוראות מפורטות יותר לתחילת העבודה מופיעות בקובץ README שמופץ עם ספריית הלקוח של Ruby. בנוסף, תוכלו לעיין בספרייה לדוגמה המלאה של Ruby.

השלבים הבאים

כשיש לכם ספריית לקוח פעילה, תוכלו לשנות את הדוגמאות כדי להרחיב אותן לצרכים שלכם.

במסמכי התיעוד תוכלו לקרוא מידע נוסף על ה-API.

לקבלת עזרה, אפשר להיכנס לדף התמיכה שלנו.

שנתחיל?

קבלת גישה לרשת של Ad Manager

יצירת פרטי כניסה לאימות

הגדרה של רשת Ad Manager

הגדרת הלקוח

Java

Python

PHP‏

‎.NET

Ruby

השלבים הבאים