Có 3 phương pháp để truy xuất các thực thể và báo cáo dữ liệu bằng API Google Ads.
GoogleAdsService.SearchStreamGoogleAdsService.Search- GET yêu cầu
Hướng dẫn này chủ yếu tập trung vào việc phát trực tuyến dữ liệu từ GoogleAdsService. Dưới đây là những điểm khác biệt cấp cao của ba phương thức truy xuất dữ liệu:
| GoogleAdsService.SearchStream | GoogleAdsService.Search | GET yêu cầu | |
|---|---|---|---|
| Phù hợp với mã sản xuất | Có | Có | No (chỉ để gỡ lỗi) |
| Dịch vụ | GoogleAdsService |
GoogleAdsService |
Các dịch vụ dành riêng cho tài nguyên (ví dụ: CampaignService) |
| Trường hợp | Tìm nạp đối tượng và báo cáo | Tìm nạp đối tượng và báo cáo | Tìm nạp đối tượng |
| Phản hồi | Luồng đối tượng GoogleAdsRow |
Trang của các đối tượng GoogleAdsRow |
Một đối tượng (ví dụ: Campaign) |
| Các trường của phản hồi | Chỉ những mục được chỉ định trong truy vấn | Chỉ những mục được chỉ định trong truy vấn | Đã điền sẵn tất cả các trường |
| Giới hạn hằng ngày | Giới hạn hằng ngày dựa trên các cấp truy cập | Giới hạn hằng ngày dựa trên các cấp truy cập | 1.000 yêu cầu mỗi ngày |
SearchStream so với Tìm kiếm
Mặc dù Search có thể gửi nhiều yêu cầu phân trang để tải toàn bộ báo cáo xuống, nhưng SearchStream gửi một yêu cầu duy nhất và bắt đầu một kết nối liên tục với API Google Ads, bất kể kích thước báo cáo.
Đối với SearchStream, các gói dữ liệu bắt đầu tải xuống ngay lập tức và toàn bộ
kết quả được lưu vào bộ nhớ đệm. Mã của bạn có thể bắt đầu đọc dữ liệu lưu vào bộ đệm mà không cần phải đợi toàn bộ luồng kết thúc.
Bằng cách loại bỏ thời gian mạng trọn vòng cần thiết để yêu cầu từng trang phản hồi Search, tùy thuộc vào ứng dụng của bạn, SearchStream có thể cải thiện hiệu suất so với phân trang, đặc biệt là đối với các báo cáo lớn hơn.
Ví dụ:
Ví dụ: lấy báo cáo bao gồm 100,000 hàng. Bảng sau đây phân tích sự khác biệt về kế toán giữa hai phương thức.
| Tìm kiếm luồng | Tìm kiếm | |
|---|---|---|
| Kích thước trang | Không áp dụng | 10.000 hàng mỗi trang |
| Số lượng yêu cầu API | 1 yêu cầu | 10 yêu cầu |
| Số lượng phản hồi API | 1 luồng liên tục | 10 câu trả lời |
Yếu tố hiệu suất
Nhìn chung, bạn nên chọn SearchStream thay vì Search vì những lý do sau.
Đối với các báo cáo trang đơn (dưới 10.000 hàng): Không có sự khác biệt đáng kể về hiệu suất giữa hai phương thức.
Đối với nhiều báo cáo trang:
SearchStreamthường nhanh hơn vì tránh nhiều lần khứ hồi và việc đọc/ghi từ bộ nhớ đệm trên ổ đĩa ít được xem xét hơn.
Giới hạn số lần gọi
Giới hạn hằng ngày của cả hai phương thức đều tuân thủ giới hạn chuẩn và các cấp truy cập của mã nhà phát triển. Một truy vấn hoặc báo cáo duy nhất được tính là một thao tác bất kể kết quả được phân trang hoặc phát trực tuyến.
Ví dụ về mã
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.V13.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;
}
}
1.199
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::V13::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;
}