שנתחיל?

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

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

כך יוצרים את בקשת ה-API הראשונה:

איך מקבלים גישה לרשת Ad Manager

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

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

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

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

  1. פותחים את הדף Credentials של מסוף Google API

  2. בתפריט הפרויקט, בוחרים באפשרות Create project, נותנים שם לפרויקט. אפשר גם לערוך את מזהה הפרויקט הרלוונטי. לוחצים על יצירה.

  3. בדף Credentials, בוחרים באפשרות Create credentials ואז בוחרים באפשרות Service account key.

  4. בוחרים באפשרות New service account (חשבון שירות חדש) ואז בוחרים ב-JSON כסוג המפתח.

  5. לוחצים על יצירה כדי להוריד קובץ שמכיל מפתח פרטי.

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

  1. נכנסים אל Google Ad Manager.

  2. בסרגל הצד, לוחצים על ניהול > הגדרות גלובליות.

  3. בקטע הגדרות כלליות > גישת API, לוחצים על פס ההזזה כדי לעבור למצב מופעלת.

  4. לוחצים על הלחצן שמירה בחלק התחתון של הדף.

הגדרת הלקוח

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

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

Java

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

  1. הגדרה של פרטי הכניסה

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

    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
    [...]
  2. ציון של יחסי תלות

    עורכים את הקובץ 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>

  3. כותבים קוד ושולחים בקשה.

    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.v202402.Network;
    import com.google.api.ads.admanager.axis.v202402.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());
      }
    }
    

Python

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

  1. התקנת הספרייה והגדרת פרטי הכניסה שלך.

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

    pip install googleads
    curl https://raw.githubusercontent.com/googleads/googleads-python-lib/main/googleads.yaml \
         -o ~/googleads.yaml
    
  2. הגדרת הקובץ ~/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
    
  3. מריצים קוד ושולחים בקשה.
    # 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='v202402')
    
    # 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']))
    

PHP

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

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

    מריצים את הפקודות הבאות במעטפת כדי להתקין את ספריית הלקוח ולהוריד את הקובץ 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
  2. מגדירים את הקובץ ~/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"
    
  3. מריצים קוד ושולחים בקשה.
    <?php
    require 'vendor/autoload.php';
    use Google\AdsApi\AdManager\AdManagerSession;
    use Google\AdsApi\AdManager\AdManagerSessionBuilder;
    use Google\AdsApi\AdManager\v202402\ApiException;
    use Google\AdsApi\AdManager\v202402\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()
    );
    

‎.NET

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

  1. יצירת פרויקט חדש

    פותחים את Visual Studio ויוצרים פרויקט חדש (אפליקציית Console).

  2. הוספת קובצי עזר נדרשים מהספרייה לפרויקט

    מוסיפים תלות nuget ל-Google.Dfp.

  3. הגדרה של App.config

    מעתיקים את src\App.config לספריית הפרויקט ומוסיפים אותו לפרויקט. אם לאפליקציה שלכם יש App.config משלה, אתם יכולים להעתיק את הצמתים הבאים ל-App.config:

    • הגדרות אישיות/AdManagerApi
    • configuration/configSections/section[name="AdManagerApi"]
    • configuration/system.net
  4. הגדרת פרטי הכניסה

    פותחים את 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" />
    

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

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

    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 ללא ספריית הלקוח, עיינו במאמר של NoClientLibrary ב-wiki.

Ruby

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

  1. מתקינים את אבן החן של Ruby ומורידים את קובץ התצורה.

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

    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
    
  2. הגדרה של פרטי הכניסה

    מאכלסים את שדות החובה בקובץ ~/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
    
  3. כותבים קוד ושולחים בקשה.
    # 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, :v202402)
    
    # Make a request.
    network = network_service.get_current_network()
    
    puts "The current network is %s (%d)." %
            [network[:display_name], network[:network_code]]
    

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

השלבים הבאים

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

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

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