שנתחיל?

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

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

איך ניגשים לרשת Ad Manager

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

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

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

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

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

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

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

הגדרת הלקוח

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

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

Java

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

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

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

    curl https://raw.githubusercontent.com/googleads/googleads-java-lib/master/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.v202302.Network;
    import com.google.api.ads.admanager.axis.v202302.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 v3.6 ואילך. לקבלת מידע מפורט יותר על השימוש, אפשר לקרוא את הקובץ README בהפצה של ספריית הלקוחות.

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

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

    pip install googleads
    curl https://raw.githubusercontent.com/googleads/googleads-python-lib/master/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='v202302')
    
    # 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/master/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\v202302\ApiException;
    use Google\AdsApi\AdManager\v202302\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. הוספה של הפניות נדרשות לספרייה לפרויקט

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

Ruby

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

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

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

    gem install google-dfp-api
    curl https://raw.githubusercontent.com/googleads/google-api-ads-ruby/master/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, :v202302)
    
    # 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, אפשר לעיין במסמכי התיעוד.

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