الإبلاغ عن البث

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

هناك ثلاث طرق لاسترداد الكيانات وإعداد تقارير البيانات باستخدام إعلانات Google API.

يركّز هذا الدليل بشكل أساسي على بث البيانات من GoogleAdsService. في ما يلي اختلافات عالية المستوى لطرق استرداد البيانات الثلاث:

GoogleAdsService.SearchStream إعلانات GoogleService.Search طلبات GET
مناسبة لرمز الإنتاج نعم نعم لا (لتصحيح الأخطاء فقط)
خدمة GoogleAdsService GoogleAdsService الخدمات الخاصة بالموارد (على سبيل المثال، CampaignService)
السيناريو جلب الكائنات والتقارير جلب الكائنات والتقارير جارٍ جلب الكائنات
الإجابة ساحة مشاركات من GoogleAdsRow الكائنات صفحات كائنات GoogleAdsRow كائن واحد (على سبيل المثال، Campaign)
حقول الرد فقط المحدّدة في طلب البحث فقط المحدّدة في طلب البحث تم ملء جميع الحقول
الحدود اليومية الحدود اليومية بناءً على مستويات الوصول الحدود اليومية بناءً على مستويات الوصول 1000 طلب في اليوم

على الرغم من أن خدمة Search يمكنها إرسال عدة طلبات مقسّمة على صفحات لتنزيل التقرير بالكامل، فإن SearchStream تُرسل طلبًا واحدًا وتبدأ اتصالاً مستمرًا مع Google Ads API بغض النظر عن حجم التقرير.

بالنسبة إلى SearchStream، يبدأ تنزيل حزم البيانات على الفور مع تخزين النتيجة مؤقتًا بالكامل في المخزن المؤقت للبيانات. يمكن للشفرة بدء قراءة البيانات المخزنة مؤقتًا بدون الحاجة إلى انتظار انتهاء البث المباشر بأكمله.

من خلال الحد من وقت الشبكة ذهابًا وإيابًا المطلوب لطلب كل صفحة فردية من استجابة Search، بناءً على تطبيقك، يمكن لـ SearchStream تقديم أداء مُحسَّن على الصفحات، خاصةً للتقارير الكبيرة.

مثال

على سبيل المثال، تقرير يحتوي على 100,000 صف. يوضح الجدول التالي الفروق بين طريقتَي الدفع.

ساحة مشاركات البحث بحث
حجم الصفحة غير سارية 10000 صف في الصفحة
عدد طلبات البيانات من واجهة برمجة التطبيقات طلب واحد 10 طلبات
عدد استجابات واجهة برمجة التطبيقات ساحة مشاركات واحدة متواصلة 10 ردود

عوامل الأداء

بوجه عام، نقترح SearchStream على Search للأسباب التالية.

  • بالنسبة إلى تقارير الصفحة الواحدة (أقل من 10000 صف): لا توجد اختلافات كبيرة في الأداء بين الطريقتين.

  • بالنسبة إلى تقارير الصفحات المتعددة: يكون المسار SearchStream عادةً أسرع نظرًا لأنه يتم تجنب العديد من جولات الذهاب والإياب وأن القراءة/الكتابة من ذاكرة التخزين المؤقت على القرص تكون أقل عاملاً.

حدود المعدّل

تلتزم الحدود اليومية لكلتا الطريقتين بالحدود القياسية ومستويات الوصول إلى الرمز المميز للمطوِّر. يتم احتساب طلب بحث أو تقرير واحد كعملية واحدة بغض النظر عن النتيجة التي يتم وضعها في الصفحة أو البث.

أمثلة على الرموز

لغة Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String searchQuery =
        "SELECT campaign.id, "
            + "campaign.name, "
            + "ad_group.id, "
            + "ad_group.name, "
            + "ad_group_criterion.criterion_id, "
            + "ad_group_criterion.keyword.text, "
            + "ad_group_criterion.keyword.match_type, "
            + "metrics.impressions, "
            + "metrics.clicks, "
            + "metrics.cost_micros "
            + "FROM keyword_view "
            + "WHERE segments.date DURING LAST_7_DAYS "
            + "AND campaign.advertising_channel_type = 'SEARCH' "
            + "AND ad_group.status = 'ENABLED' "
            + "AND ad_group_criterion.status IN ('ENABLED', 'PAUSED') "
            // Limits to the 50 keywords with the most impressions in the date range.
            + "ORDER BY metrics.impressions DESC "
            + "LIMIT 50";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(searchQuery)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all of the
    // requested field values for the keyword.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through the results in the stream response and prints all of the requested
    // field values for the keyword in each row.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        Campaign campaign = googleAdsRow.getCampaign();
        AdGroup adGroup = googleAdsRow.getAdGroup();
        AdGroupCriterion adGroupCriterion = googleAdsRow.getAdGroupCriterion();
        Metrics metrics = googleAdsRow.getMetrics();

        System.out.printf(
            "Keyword text '%s' with "
                + "match type '%s' "
                + "and ID %d "
                + "in ad group '%s' "
                + "with ID %d "
                + "in campaign '%s' "
                + "with ID %d "
                + "had %d impression(s), "
                + "%d click(s), "
                + "and %d cost (in micros) "
                + "during the last 7 days.%n",
            adGroupCriterion.getKeyword().getText(),
            adGroupCriterion.getKeyword().getMatchType(),
            adGroupCriterion.getCriterionId(),
            adGroup.getName(),
            adGroup.getId(),
            campaign.getName(),
            campaign.getId(),
            metrics.getImpressions(),
            metrics.getClicks(),
            metrics.getCostMicros());
      }
    }
  }
}
      

#C

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

    // Create the query.
    string query =
        @"SELECT
         campaign.id,
         campaign.name,
         ad_group.id,
         ad_group.name,
         ad_group_criterion.criterion_id,
         ad_group_criterion.keyword.text,
         ad_group_criterion.keyword.match_type,
         metrics.impressions,
         metrics.clicks,
         metrics.cost_micros
     FROM keyword_view
     WHERE segments.date DURING LAST_7_DAYS
         AND campaign.advertising_channel_type = 'SEARCH'
         AND ad_group.status = 'ENABLED'
         AND ad_group_criterion.status IN ('ENABLED','PAUSED')
     ORDER BY metrics.impressions DESC
     LIMIT 50";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                // Display the results.
                foreach (GoogleAdsRow criterionRow in resp.Results)
                {
                    Console.WriteLine(
                        "Keyword with text " +
                        $"'{criterionRow.AdGroupCriterion.Keyword.Text}', match type " +
                        $"'{criterionRow.AdGroupCriterion.Keyword.MatchType}' and ID " +
                        $"{criterionRow.AdGroupCriterion.CriterionId} in ad group " +
                        $"'{criterionRow.AdGroup.Name}' with ID " +
                        $"{criterionRow.AdGroup.Id} in campaign " +
                        $"'{criterionRow.Campaign.Name}' with ID " +
                        $"{criterionRow.Campaign.Id} had " +
                        $"{criterionRow.Metrics.Impressions.ToString()} impressions, " +
                        $"{criterionRow.Metrics.Clicks} clicks, and " +
                        $"{criterionRow.Metrics.CostMicros} cost (in micros) during the " +
                        "last 7 days.");
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
      

لغة PHP

public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all keyword statistics.
    $query =
        "SELECT campaign.id, "
            . "campaign.name, "
            . "ad_group.id, "
            . "ad_group.name, "
            . "ad_group_criterion.criterion_id, "
            . "ad_group_criterion.keyword.text, "
            . "ad_group_criterion.keyword.match_type, "
            . "metrics.impressions, "
            . "metrics.clicks, "
            . "metrics.cost_micros "
        . "FROM keyword_view "
        . "WHERE segments.date DURING LAST_7_DAYS "
            . "AND campaign.advertising_channel_type = 'SEARCH' "
            . "AND ad_group.status = 'ENABLED' "
            . "AND ad_group_criterion.status IN ('ENABLED', 'PAUSED') "
        // Limits to the 50 keywords with the most impressions in the date range.
        . "ORDER BY metrics.impressions DESC "
        . "LIMIT 50";

    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream =
        $googleAdsServiceClient->searchStream($customerId, $query);

    // Iterates over all rows in all messages and prints the requested field values for
    // the keyword in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        $campaign = $googleAdsRow->getCampaign();
        $adGroup = $googleAdsRow->getAdGroup();
        $adGroupCriterion = $googleAdsRow->getAdGroupCriterion();
        $metrics = $googleAdsRow->getMetrics();
        printf(
            "Keyword text '%s' with "
            . "match type %s "
            . "and ID %d "
            . "in ad group '%s' "
            . "with ID %d "
            . "in campaign '%s' "
            . "with ID %d "
            . "had %d impression(s), "
            . "%d click(s), "
            . "and %d cost (in micros) "
            . "during the last 7 days.%s",
            $adGroupCriterion->getKeyword()->getText(),
            KeywordMatchType::name($adGroupCriterion->getKeyword()->getMatchType()),
            $adGroupCriterion->getCriterionId(),
            $adGroup->getName(),
            $adGroup->getId(),
            $campaign->getName(),
            $campaign->getId(),
            $metrics->getImpressions(),
            $metrics->getClicks(),
            $metrics->getCostMicros(),
            PHP_EOL
        );
    }
}
      

لغة Python

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

    query = """
        SELECT
          campaign.id,
          campaign.name,
          ad_group.id,
          ad_group.name,
          ad_group_criterion.criterion_id,
          ad_group_criterion.keyword.text,
          ad_group_criterion.keyword.match_type,
          metrics.impressions,
          metrics.clicks,
          metrics.cost_micros
        FROM keyword_view WHERE segments.date DURING LAST_7_DAYS
        AND campaign.advertising_channel_type = 'SEARCH'
        AND ad_group.status = 'ENABLED'
        AND ad_group_criterion.status IN ('ENABLED', 'PAUSED')
        ORDER BY metrics.impressions DESC
        LIMIT 50"""

    # Issues a search request using streaming.
    search_request = client.get_type("SearchGoogleAdsStreamRequest")
    search_request.customer_id = customer_id
    search_request.query = query
    stream = ga_service.search_stream(search_request)
    for batch in stream:
        for row in batch.results:
            campaign = row.campaign
            ad_group = row.ad_group
            criterion = row.ad_group_criterion
            metrics = row.metrics
            print(
                f'Keyword text "{criterion.keyword.text}" with '
                f'match type "{criterion.keyword.match_type.name}" '
                f"and ID {criterion.criterion_id} in "
                f'ad group "{ad_group.name}" '
                f'with ID "{ad_group.id}" '
                f'in campaign "{campaign.name}" '
                f"with ID {campaign.id} "
                f"had {metrics.impressions} impression(s), "
                f"{metrics.clicks} click(s), and "
                f"{metrics.cost_micros} cost (in micros) during "
                "the last 7 days."
            )
      

Ruby

def get_keyword_stats(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

  ga_service = client.service.google_ads

  # Limits to the 50 keywords with the most impressions in the date range.
  # If you wish to exclude entries with zero impressions, include a
  # predicate in the WHERE statement like 'metrics.impressions > 0'
  query = <<~QUERY
    SELECT campaign.id,
           campaign.name,
           ad_group.id,
           ad_group.name,
           ad_group_criterion.criterion_id,
           ad_group_criterion.keyword.text,
           ad_group_criterion.keyword.match_type,
           metrics.impressions,
           metrics.clicks,
           metrics.cost_micros
    FROM keyword_view
    WHERE segments.date DURING LAST_7_DAYS
      AND campaign.advertising_channel_type = 'SEARCH'
      AND ad_group.status = 'ENABLED'
      AND ad_group_criterion.status IN ('ENABLED', 'PAUSED')
    ORDER BY metrics.impressions DESC
    LIMIT 50
  QUERY

  responses = ga_service.search_stream(customer_id: customer_id, query: query)

  responses.each do |response|
    response.results.each do |row|
      campaign = row.campaign
      ad_group = row.ad_group
      criterion = row.ad_group_criterion
      metrics = row.metrics

      puts "Keyword text '#{criterion.keyword.text}' with match type "\
        "'#{criterion.keyword.match_type}' and ID #{criterion.criterion_id} in "\
        "ad group '#{ad_group.name}' with ID #{ad_group.id} in campaign "\
        "'#{campaign.name}' with ID #{campaign.id} had #{metrics.impressions} "\
        "impression(s), #{metrics.clicks} click(s), and #{metrics.cost_micros} "\
        "cost (in micros) during the last 7 days."
    end
  end
end
      

Perl

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

  # Limit to the 50 keywords with the most impressions in the date range.
  # If you wish to exclude entries with zero impressions, include a
  # predicate in the WHERE statement like 'metrics.impressions > 0'.
  my $search_query =
    "SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, " .
    "ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, " .
    "ad_group_criterion.keyword.match_type, " .
    "metrics.impressions, metrics.clicks, metrics.cost_micros " .
    "FROM keyword_view WHERE segments.date DURING LAST_7_DAYS " .
    "AND campaign.advertising_channel_type = 'SEARCH' " .
    "AND ad_group.status = 'ENABLED' " .
    "AND ad_group_criterion.status IN ('ENABLED', 'PAUSED') " .
    "ORDER BY metrics.impressions DESC LIMIT 50";

  # Create a search Google Ads stream request that will retrieve all keyword
  # statistics.
  my $search_stream_request =
    Google::Ads::GoogleAds::V12::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      => $search_query,
    });

  # 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 keyword in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row     = shift;
      my $campaign           = $google_ads_row->{campaign};
      my $ad_group           = $google_ads_row->{adGroup};
      my $ad_group_criterion = $google_ads_row->{adGroupCriterion};
      my $metrics            = $google_ads_row->{metrics};

      printf "Keyword text '%s' with match type '%s' and ID %d in ad group" .
        " '%s' with ID %d in campaign '%s' with ID %d had %d impression(s), " .
        "%d click(s), and %d cost (in micros) during the last 7 days.\n",
        $ad_group_criterion->{keyword}{text},
        $ad_group_criterion->{keyword}{matchType},
        $ad_group_criterion->{criterionId},
        $ad_group->{name},
        $ad_group->{id},
        $campaign->{name},
        $campaign->{id},
        $metrics->{impressions},
        $metrics->{clicks},
        $metrics->{costMicros};
    });

  return 1;
}