ביצוע קריאה ל-API

במדריך הזה נדרשות כמה הגדרות מוקדמות שהוגדרו בשלבים הקודמים. אם עדיין לא עשיתם זאת, כדאי להתחיל בקטע מבוא.

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

אחזור של אסימון רענון

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

oauth2l

1. מריצים את הכלי oauth2l כדי ליצור את אסימון הרענון:

   oauth2l fetch --credentials credentials.json --scope adwords \
       --output_format refresh_token

   קובץ credentials.json הוא משלב קודם.

2. הפקודה oauth2l פותחת חלון כניסה לחשבון Google בחלון דפדפן חדש, ומובילה אתכם דרך שלבי האימות של OAuth 2.0.

   חשוב להיכנס באמצעות כתובת האימייל מהשלב שבו זיהית את מספר הלקוח להתחברות.

   אם האפליקציה לא מאומתת, יכול להיות שיופיע מסך אזהרה. במקרים כאלה, אפשר ללחוץ בבטחה על הקישור Show Advanced (הצגת הגדרות מתקדמות) ואז על האפשרות Go to PROJECT_NAME (unverified) (מעבר אל PROJECT_NAME (לא מאומת)).

   

3. אחרי שמאמתים את ההיקפים, מעניקים את ההרשאה בלחיצה על הלחצן Continue.

   תופיע בקשה בדפדפן עם הטקסט הבא:

   Authorization code granted. Close this tab.
   

   הפלט של הפקודה oauth2l הוא קטע ה-JSON הבא:

   {
     "client_id": "******.apps.googleusercontent.com",
     "client_secret": "******",
     "token_uri": "https://oauth2.googleapis.com/token",
     "auth_uri": "https://accounts.google.com/o/oauth2/auth",
     "refresh_token": "******",
     "type": "authorized_user"
   }
   

CLI של gcloud

1. יוצרים את אסימון הרענון באמצעות הכלי CLI של gcloud:

   gcloud auth application-default \
     login --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
     --client-id-file=<path_to_credentials.json>

   קובץ credentials.json הוא משלב קודם.

2. הפקודה gcloud פותחת חלון כניסה לחשבון Google בחלון דפדפן חדש, ומובילה אתכם דרך שלבי האימות של OAuth 2.0.

   חשוב להיכנס באמצעות כתובת האימייל מהשלב שבו זיהית את מספר הלקוח להתחברות.

   אם האפליקציה לא מאומתת, יכול להיות שיופיע מסך אזהרה. במקרים כאלה, אפשר ללחוץ בבטחה על הקישור Show Advanced (הצגת הגדרות מתקדמות) ואז על האפשרות Go to PROJECT_NAME (unverified) (מעבר אל PROJECT_NAME (לא מאומת)).

   

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

   הדפדפן עובר לכתובת https://cloud.google.com/sdk/auth_success,‏ שמציינת שהאימות הצליח.

   Authorization code granted. Close this tab.
   

   הפלט של הפקודה gcloud נראה כך:

   Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]
   

   עכשיו פותחים את הקובץ application_default_credentials.json. התוכן שלו אמור להיראות כך:

   {
     "account": "",
     "client_id": "******.apps.googleusercontent.com",
     "client_secret": "******",
     "refresh_token": "******",
     "type": "authorized_user",
     "universe_domain": "googleapis.com"
   }
   

אחרים

אם אתם מעדיפים להשתמש ב-curl או בלקוח HTTP משלכם, תוכלו לעיין בדוגמה במדריך OAuth 2.0 לאפליקציות לנייד ולמחשב.

שליחת קריאה ל-API

בוחרים את הלקוח הרצוי כדי לקבל הוראות לשליחת קריאה ל-API:

Java

הארטיפקטים של ספריית הלקוח מתפרסמים במאגר המרכזי של Maven. מוסיפים את ספריית הלקוח כיחס תלות לפרויקט באופן הבא:

תלות Maven:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>34.0.0</version>
</dependency>

יחסי התלות ב-Gradle הם:

implementation 'com.google.api-ads:google-ads:34.0.0'

יוצרים קובץ ~/ads.properties עם התוכן הבא:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

יוצרים אובייקט GoogleAdsClient באופן הבא:

GoogleAdsClient googleAdsClient = null;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
  System.err.printf(
      "Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
      fnfe);
  System.exit(1);
} catch (IOException ioe) {
  System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
  System.exit(1);
}

בשלב הבא, מריצים דוח קמפיינים באמצעות השיטה GoogleAdsService.SearchStream כדי לאחזר את הקמפיינים בחשבון. המדריך הזה לא מכיל פרטים על דיווח.

    private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}
GetCampaigns.java

C#‎

חבילות ספריות הלקוח מתפרסמות במאגר Nuget.org. מתחילים בהוספת הפניה ל-nuget לחבילה Google.Ads.GoogleAds.

dotnet add package Google.Ads.GoogleAds --version 18.1.0

יוצרים אובייקט GoogleAdsConfig עם ההגדרות הרלוונטיות, ומשתמשים בו כדי ליצור אובייקט GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = "APPLICATION",
    OAuth2ClientId = "******.apps.googleusercontent.com",
    OAuth2ClientSecret = "******",
    OAuth2RefreshToken = "******",
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

בשלב הבא, מריצים דוח קמפיינים באמצעות השיטה GoogleAdsService.SearchStream כדי לאחזר את הקמפיינים בחשבון. המדריך הזה לא מכיל פרטים על דיווח.

    public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V18.GoogleAdsService);

    // Create a query that will retrieve all campaigns.
    string query = @"SELECT
                    campaign.id,
                    campaign.name,
                    campaign.network_settings.target_content_network
                FROM campaign
                ORDER BY campaign.id";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
GetCampaigns.cs

PHP

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

composer require googleads/google-ads-php:25.0.0

יוצרים עותק של הקובץ google_ads_php.ini מהמאגר ב-GitHub ומשנים אותו כך שיכלול את פרטי הכניסה.

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

יוצרים מופע של אובייקט GoogleAdsClient.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

בשלב הבא, מריצים דוח קמפיינים באמצעות השיטה GoogleAdsService.SearchStream כדי לאחזר את הקמפיינים בחשבון. המדריך הזה לא מכיל פרטים על דיווח.

    public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}
GetCampaigns.php

Python

ספריית הלקוח מופצת ב-PyPI וניתן להתקין אותה באמצעות הפקודה pip באופן הבא:

python -m pip install google-ads==21.3.0

יוצרים עותק של הקובץ google-ads.yaml מהמאגר ב-GitHub ומשנים אותו כך שיכלול את פרטי הכניסה שלכם.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE
developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

יוצרים מכונה של GoogleAdsClient על ידי קריאה ל-method‏ GoogleAdsClient.load_from_storage. מעבירים את הנתיב ל-google-ads.yaml כמחרוזת לשיטה בזמן הקריאה אליה:

from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

בשלב הבא, מריצים דוח קמפיינים באמצעות השיטה GoogleAdsService.SearchStream כדי לאחזר את הקמפיינים בחשבון. המדריך הזה לא מכיל פרטים על דיווח.

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")

    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream = ga_service.search_stream(customer_id=customer_id, query=query)

    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )
get_campaigns.py

Ruby

הג'אמס של Ruby לספריית הלקוח מתפרסמים באתר האירוח של הג'אמס של Rubygems. הדרך המומלצת להתקנה היא באמצעות bundler. מוסיפים שורה ל-Gemfile:

gem 'google-ads-googleads', '~> 30.0.0'

לאחר מכן מריצים את הפקודה:

bundle install

יוצרים עותק של הקובץ google_ads_config.rb מהמאגר ב-GitHub ומשנים אותו כך שיכלול את פרטי הכניסה.

Google::Ads::GoogleAds::Config.new do |c|
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

יוצרים מכונה של GoogleAdsClient על ידי העברת הנתיב שבו שמור הקובץ.

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

בשלב הבא, מריצים דוח קמפיינים באמצעות השיטה GoogleAdsService.SearchStream כדי לאחזר את הקמפיינים בחשבון. המדריך הזה לא מכיל פרטים על דיווח.

    def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
end
get_campaigns.rb

Perl

הספרייה מופצת ב-CPAN. קודם כול, משכפלים את המאגר google-ads-perl בספרייה הרצויה.

git clone https://github.com/googleads/google-ads-perl.git

עוברים לספרייה google-ads-perl ומריצים את הפקודה הבאה בשורת הפקודה כדי להתקין את כל יחסי התלות הנדרשים לשימוש בספרייה.

cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps

יוצרים עותק של הקובץ googleads.properties מהמאגר ב-GitHub ומשנים אותו כך שיכלול את פרטי הכניסה.

clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

יוצרים מכונה של Client ומעבירים את הנתיב למיקום שבו שומרים את הקובץ.

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file
});

בשלב הבא, מריצים דוח קמפיינים באמצעות השיטה GoogleAdsService.SearchStream כדי לאחזר את הקמפיינים בחשבון. המדריך הזה לא מכיל פרטים על דיווח.

    sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V18::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}
get_campaigns.pl

REST

מתחילים להשתמש בלקוח HTTP כדי לאחזר אסימון גישה מסוג OAuth 2.0. במדריך הזה נעשה שימוש בפקודה curl.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

בשלב הבא, מריצים דוח קמפיינים באמצעות השיטה GoogleAdsService.SearchStream כדי לאחזר את הקמפיינים בחשבון. המדריך הזה לא מכיל פרטים על דיווח.

curl -i -X POST https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

התוכן של query.json הוא:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}