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

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

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

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

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

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

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

    הקובץ credentials.json הוא מגרסה קודמת בפעימה הזו.

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

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

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

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

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

    Authorization code granted. Please 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"
    }
    

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

כדי לקבל הוראות לביצוע קריאה ל-API, צריך לבחור את הלקוח הרצוי:

Java

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

התלות של Maven היא:

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

התלות של Gradle היא:

implementation 'com.google.api-ads:google-ads:33.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());
      }
    }
  }
}

C#‎

החבילות של ספריית הלקוח מתפרסמות ב-Nuget.org מאגר הנתונים. קודם כול צריך להוסיף הפניה לחבילת 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.V17.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;
    }
}

PHP

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

composer require googleads/google-ads-php:22.0.0

ליצור עותק של google_ads_php.ini ממאגר ה-GitHub של 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
        );
    }
}

Python

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

python -m pip install google-ads==21.3.0

ליצור עותק של google-ads.yaml ממאגר ה-GitHub של 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 באמצעות הפקודה GoogleAdsClient.load_from_storage. מעבירים את הנתיב אל google-ads.yaml כמחרוזת ל-method כשקוראים לה:

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.'
            )

Ruby

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

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

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

bundle install

ליצור עותק של google_ads_config.rb ממאגר ה-GitHub של 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

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 של 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::V17::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;
}

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/v17/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"
}