ביצוע קריאה ל-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
``` The `credentials.json` file is from a [previous
step](/google-ads/api/docs/get-started/oauth-cloud-project#id-secret).

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

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

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

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

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

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

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>
``` The `credentials.json` file is from a [previous
step](/google-ads/api/docs/get-started/oauth-cloud-project#id-secret).

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

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

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

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

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

    Authorization code granted. Please 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>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());
      }
    }
  }
}
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.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;
    }
}
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 באמצעות הפקודה 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.'
            )
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 של 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;
}
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"
}
הקודם
הורדת כלים וספריות
הבא
שגיאות נפוצות