عرض التقارير باستخدام GoogleAdsService

لاسترداد عناصر Google Ads API وبيانات التقارير، استخدِم إحدى الطريقتَين التاليتَين:

في ما يلي الفروق الرئيسية بين الطريقتَين:

GoogleAdsService.SearchStream GoogleAdsService.Search
مناسب لرمز الإنتاج نعم نعم
الخدمة GoogleAdsService GoogleAdsService
السيناريو استرداد الكائنات والتقارير استرداد الكائنات والتقارير
الردّ تدفق GoogleAdsRow من العناصر صفحات تتضمّن GoogleAdsRow عنصر
حقول الردّ تلك المحدّدة في طلب البحث فقط تلك المحدّدة في طلب البحث فقط
الحدود اليومية الحدود اليومية استنادًا إلى مستويات الوصول الحدود اليومية استنادًا إلى مستويات الوصول

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

بالنسبة إلى SearchStream، تبدأ حِزم البيانات في التنزيل على الفور في مجموعات من SearchGoogleAdsStreamResponse عنصر. يمكن أن يتكرّر الرمز البرمجي على دفعات واردة عند وصولها بدون انتظار انتهاء البث بأكمله.

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

مثال

يتناول هذا المثال تقريرًا يتألف من 100,000 صف. يوضّح الجدول التالي الاختلافات بين الطلب والاستجابة في الطريقتَين:

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

عوامل الأداء

في معظم حالات الاستخدام، ننصحك باستخدام SearchStream بدلاً من Search للأسباب التالية:

  • التقارير المكوّنة من صفحة واحدة (أقل من 10,000 صف): ليس هناك اختلافات كبيرة في الأداء بين الطريقتَين.
  • التقارير المتعدّدة الصفحات: تكون SearchStream أسرع عادةً لأنّه يتم تجنُّب عمليات نقل متعدّدة على الشبكة، كما أنّ القراءة أو الكتابة من ذاكرة التخزين المؤقت للقرص لا تشكّل عاملاً مهمًا.
  • كفاءة الذاكرة: عند معالجة التقارير الكبيرة باستخدام SearchStream، كرِّر أجزاء البث وعالج الصفوف عند وصولها بدلاً من تخزين جميع الصفوف مؤقتًا في الذاكرة في وقت واحد لتجنُّب أخطاء نفاد الذاكرة.
  • مرونة الاتصال: بما أنّ SearchStream يعتمد على اتصال دائم، يمكن أن تنقطع عمليات البث الطويلة بسبب انقطاع الاتصال بالشبكة أو انتهاء المهلة. اضبط مهلات RPC المناسبة ونفِّذ منطق إعادة المحاولة للأخطاء العابرة في البث.

حدود معدّل الاستخدام

تلتزم حدود العمليات اليومية لكلا الطريقتين بالحدود العادية ومستويات الوصول لمشروعك على Google Cloud. يتم احتساب طلب بحث واحد منطقي للتقرير كعملية واحدة ضمن حصة العمليات اليومية بغض النظر عمّا إذا كان يتم بث النتيجة باستخدام SearchStream أو استرجاعها على عدة صفحات مخزّنة مؤقتًا باستخدام Search مع page_token. ومع ذلك، سيتم احتساب كل طلب Search مقسَّم إلى صفحات كطلب RPC فردي ضمن حدود المعدّل قصيرة الأجل.

مثال على الرمز

يوضّح مثال الرمز البرمجي التالي كيفية تنفيذ طلب بحث عن تقرير البث المباشر باستخدام مكتبات العميل:

جافا

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

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V25.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

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

def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

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

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )
      

Ruby

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

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::V25::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;
}
      

curl