สตรีมรายงานโดยใช้ GoogleAdsService

หากต้องการดึงข้อมูลเอนทิตีและข้อมูลการรายงานของ Google Ads API ให้ใช้วิธีใดวิธีหนึ่งต่อไปนี้

ความแตกต่างระดับสูงของทั้ง 2 วิธีมีดังนี้

GoogleAdsService.SearchStream GoogleAdsService.Search
เหมาะสำหรับโค้ดที่ใช้งานจริง ใช่ ใช่
บริการ GoogleAdsService GoogleAdsService
สถานการณ์ การดึงข้อมูลออบเจ็กต์และรายงาน การดึงข้อมูลออบเจ็กต์และรายงาน
คำตอบ สตรีม ออบเจ็กต์ GoogleAdsRow หน้าออบเจ็กต์ GoogleAdsRow
ฟิลด์ของคำตอบ เฉพาะฟิลด์ที่ระบุในคําค้นหา เฉพาะฟิลด์ที่ระบุในคําค้นหา
ขีดจำกัดการใช้งานต่อวัน ขีดจำกัดการใช้งานต่อวันตามระดับการเข้าถึง ขีดจำกัดการใช้งานต่อวันตามระดับการเข้าถึง

ขณะที่ Search ส่งคำขอแบบแบ่งหน้าหลายรายการเพื่อ ดาวน์โหลดรายงานทั้งฉบับ แต่ SearchStream จะส่ง คำขอเพียงรายการเดียวและเริ่มต้นการเชื่อมต่อ gRPC แบบต่อเนื่องกับ Google Ads API ไม่ว่ารายงานจะมีขนาดเท่าใดก็ตาม

สำหรับ SearchStream แพ็กเก็ตข้อมูลจะเริ่มดาวน์โหลดทันทีเป็นชุดๆ ของ SearchGoogleAdsStreamResponse ออบเจ็กต์ โค้ดของคุณสามารถวนซ้ำชุดข้อมูลที่เข้ามาเมื่อมาถึงโดยไม่ต้องรอให้สตรีมทั้งหมดเสร็จสิ้น

SearchStream ช่วยปรับปรุงประสิทธิภาพให้ดีขึ้นเมื่อเทียบกับการแบ่งหน้า โดยเฉพาะอย่างยิ่งสำหรับรายงานขนาดใหญ่ เนื่องจากไม่จำเป็นต้องใช้เวลาในการรับส่งข้อมูลผ่านเครือข่ายแบบไป-กลับเพื่อขอแต่ละหน้าของคำตอบ Search

ตัวอย่าง

ตัวอย่างนี้จะดูรายงานที่มี 100,000 แถว ตารางต่อไปนี้แสดงรายละเอียดความแตกต่างของคำขอและการตอบกลับระหว่าง 2 วิธี

SearchStream Search
ขนาดหน้า ไม่เกี่ยวข้อง 10,000 แถวต่อหน้า
จำนวนคำขอ API คำขอ 1 รายการ คำขอ 10 รายการ
จำนวนการตอบกลับจาก API สตรีมต่อเนื่อง 1 รายการ 10 คำตอบ

ปัจจัยด้านประสิทธิภาพ

สำหรับ Use Case ส่วนใหญ่ เราขอแนะนำให้ใช้ SearchStream แทน Search ด้วยเหตุผลต่อไปนี้

  • รายงานหน้าเดียว (ไม่เกิน 10,000 แถว): ประสิทธิภาพของทั้ง 2 วิธีไม่แตกต่างกันอย่างมีนัยสำคัญ
  • รายงานหลายหน้า: โดยปกติแล้ว SearchStream จะเร็วกว่าเนื่องจากหลีกเลี่ยงการรับส่งข้อมูลผ่านเครือข่ายหลายครั้ง และการอ่านหรือเขียนจากแคชในดิสก์มีผลน้อยลง
  • ประสิทธิภาพด้านหน่วยความจำ: เมื่อประมวลผลรายงานขนาดใหญ่ด้วย SearchStream ให้วนซ้ำผ่าน Chunk ของสตรีมและประมวลผลแถวเมื่อมาถึงแทนที่จะบัฟเฟอร์แถวทั้งหมดในหน่วยความจำพร้อมกันเพื่อหลีกเลี่ยงข้อผิดพลาดหน่วยความจำไม่พอ (OOM)
  • ความยืดหยุ่นในการเชื่อมต่อ: เนื่องจาก SearchStream อาศัยการเชื่อมต่อแบบต่อเนื่อง สตรีมที่ทำงานเป็นเวลานานจึงอาจถูกขัดจังหวะเนื่องจากเครือข่ายขาดการเชื่อมต่อหรือการหมดเวลาของกำหนดเวลา กำหนดค่าการหมดเวลา RPC ที่เหมาะสมและใช้ตรรกะการลองใหม่สำหรับข้อผิดพลาดของสตรีมชั่วคราว

การจำกัดอัตราคำขอ

ขีดจำกัดการดำเนินการต่อวันสำหรับทั้ง 2 วิธีเป็นไปตามขีดจำกัดมาตรฐานและ ระดับการเข้าถึงของโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google ระบบจะนับคําค้นหารายงานเชิงตรรกะรายการเดียวเป็นการดำเนินการ 1 รายการตามโควต้าการดำเนินการต่อวัน ไม่ว่าผลลัพธ์จะสตรีมด้วย SearchStream หรือดึงข้อมูลจากหน้าแคชหลายหน้าโดยใช้ Search กับ page_token อย่างไรก็ตาม คำขอ Search แบบแบ่งหน้าแต่ละรายการจะยังคงนับเป็นการเรียก RPC แต่ละรายการเทียบกับการจำกัดอัตราคำขอระยะสั้น

ตัวอย่างโค้ด

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีเรียกใช้คําค้นหารายงานแบบสตรีมมิงโดยใช้ไลบรารีของไคลเอ็นต์

Java

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

ก่อนหน้า
ป้ายกำกับ
ถัดไป
การกำหนดหน้า