Google Ads API でエンティティを取得し、データを報告するには、3 つの方法があります。
このガイドでは、主に GoogleAdsService からのデータのストリーミングに焦点を当てます。3 つのデータ取得方法の概要は次のとおりです。
| GoogleAdsService.SearchStream | Google 広告サービス.検索 | GET リクエスト | |
|---|---|---|---|
| 本番環境コードに適している | はい | はい | No（デバッグのみ） |
| サービス | GoogleAdsService |
GoogleAdsService |
リソース固有のサービス（CampaignService など） |
| シナリオ | オブジェクトとレポートの取得 | オブジェクトとレポートの取得 | オブジェクトの取得 |
| レスポンス | GoogleAdsRow オブジェクトのストリーム |
GoogleAdsRow オブジェクトのページ |
1 つのオブジェクト（例: Campaign） |
| レスポンスのフィールド | クエリで指定されたもののみ | クエリで指定されたもののみ | すべての項目が入力されました |
| 1 日の利用時間の上限 | アクセスレベルに基づく 1 日の上限 | アクセスレベルに基づく 1 日の上限 | 1 日あたり 1,000 回のリクエスト |
SearchStream と Search
Search では複数のページ分割リクエストを送信してレポート全体をダウンロードできますが、SearchStream では単一のリクエストが送信され、レポートサイズに関係なく Google Ads API との永続的な接続が開始されます。
SearchStream の場合、データパケットが直ちにダウンロードされ、結果全体がデータバッファにキャッシュされます。コードでは、ストリーム全体が終了するまで待つことなく、バッファ内のデータの読み取りを開始できます。
アプリによっては、Search レスポンスの個々のページをリクエストする際に必要となるラウンドトリップ ネットワーク時間が不要になるため、特に大規模なレポートの場合、ページングよりもパフォーマンスが向上します。SearchStream
例
たとえば、100,000 行で構成されるレポートを作成します。次の表に、2 つのメソッドの会計上の違いを示します。
| 検索ストリーム | 検索 | |
|---|---|---|
| ページサイズ | 該当なし | 1 ページあたり 10,000 行 |
| API リクエストの数 | 1 件のリクエスト | 10 リクエスト |
| API レスポンスの数 | 1 個の連続ストリーム | 回答 10 件 |
パフォーマンス要因
通常は、次の理由により、Search よりも SearchStream をおすすめします。
単一ページレポート（10,000 行未満）: 2 つのメソッド間でパフォーマンスに大きな違いはありません。
複数ページのレポートの場合: 複数のラウンドトリップが回避され、ディスク キャッシュの読み書きが問題にならないため、通常は
SearchStreamが高速になります。
レート制限
どちらの方法でも、1 日あたりの上限は開発者トークンの標準の上限とアクセスレベルに従います。1 つのクエリまたはレポートは、ページ分けまたはストリーミングされる結果に関係なく、1 回のオペレーションとしてカウントされます。
コードの例
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.V14.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::V14::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;
}