ラベルを使用すると、キャンペーン、広告グループ、広告、キーワードを分類し、これらのカテゴリを使用してさまざまな方法でワークフローを簡素化できます。
このガイドでは以下の作業の手順を紹介します。
LabelService
を使用して、プログラムでラベルを作成します。CampaignLabelService
リクエストを使用して、キャンペーンにラベルを割り当てます。GoogleAdsService
クエリを使用して、ラベルでレポート結果を取得し、フィルタする。
このガイドではキャンペーンに焦点を当てていますが、広告グループ、広告、キーワードでも同じ方法を使用できます。なお、API には CustomerLabelService
も含まれており、MCC アカウントで子アカウントにラベルを割り当てることができます。
使用例
ラベルを使用する一般的なシナリオは次のとおりです。
- 特定の時期にだけ有効にするキャンペーンがアカウント内にあり、それらのキャンペーンをレポートに簡単に追加または除外したい場合。
- 新しい一連のキーワードを広告グループに追加し、それらの統計情報を広告グループ内の他のキーワードと比較したい場合。
- Google 広告アカウントの各ユーザーは、それぞれキャンペーンのサブセットを管理しており、各ユーザーのキャンペーン セットを識別できるようにしたいと考えています。
- アプリは、特定のオブジェクトのステータスをマークする必要があります。
ラベルを作成する
TextLabel
オブジェクトを使用してラベルを作成します。
TextLabel
インスタンスを作成します。- この
TextLabel
の背景色を設定します。 - 説明フィールドを使用して、この
TextLabel
のテキストを入力してください。 TextLabel
をLabelOperation
でラップしてLabelService.MutateLabels
に送信します。
後のクエリのために、新しいラベルの ID をメモしておきます。ID は、MutateLabelsResponse
で返される MutateLabelResults
の resource_name
フィールドに埋め込まれます。
LabelService.GetLabel
リクエスト、GoogleAdsService
Search
または SearchStream
リクエストを使用して ID を取得することもできます。
ラベルの割り当て
ラベルは、キャンペーン、顧客、広告グループ、条件、広告に割り当てることができます。
適切なサービスで Mutate
オペレーションを使用して、ラベルを割り当てます。
たとえば、キャンペーンにラベルを割り当てるには、1 つ以上の CampaignLabelOperation
を CampaignLabelService.MutateCampaignLabels
に渡します。各 CampaignLabelOperation
には、次のフィールドを含む CampaignLabel
インスタンスが含まれています。
label
: ラベルの IDcampaign
: キャンペーンの ID
ラベルとキャンペーンのペアごとに CampaignLabel
インスタンスを作成します。create
オペレーションで CampaignLabelOperation
でラップし、CampaignService.MutateCampaignLabels
に送信します。
キャンペーン ラベルの追加
以下は、キャンペーン ラベルをキャンペーンのリストに追加するコード例です。
Java
private void runExample( GoogleAdsClient googleAdsClient, long customerId, List<Long> campaignIds, Long labelId) { // Gets the resource name of the label to be added across all given campaigns. String labelResourceName = ResourceNames.label(customerId, labelId); List<CampaignLabelOperation> operations = new ArrayList<>(campaignIds.size()); // Creates a campaign label operation for each campaign. for (Long campaignId : campaignIds) { // Gets the resource name of the given campaign. String campaignResourceName = ResourceNames.campaign(customerId, campaignId); // Creates the campaign label. CampaignLabel campaignLabel = CampaignLabel.newBuilder() .setCampaign(campaignResourceName) .setLabel(labelResourceName) .build(); operations.add(CampaignLabelOperation.newBuilder().setCreate(campaignLabel).build()); } try (CampaignLabelServiceClient campaignLabelServiceClient = googleAdsClient.getLatestVersion().createCampaignLabelServiceClient()) { MutateCampaignLabelsResponse response = campaignLabelServiceClient.mutateCampaignLabels(Long.toString(customerId), operations); System.out.printf("Added %d campaign labels:%n", response.getResultsCount()); for (MutateCampaignLabelResult result : response.getResultsList()) { System.out.println(result.getResourceName()); } } }
C#
public void Run(GoogleAdsClient client, long customerId, long[] campaignIds, long labelId) { // Get the CampaignLabelServiceClient. CampaignLabelServiceClient campaignLabelService = client.GetService(Services.V16.CampaignLabelService); // Gets the resource name of the label to be added across all given campaigns. string labelResourceName = ResourceNames.Label(customerId, labelId); List<CampaignLabelOperation> operations = new List<CampaignLabelOperation>(); // Creates a campaign label operation for each campaign. foreach (long campaignId in campaignIds) { // Gets the resource name of the given campaign. string campaignResourceName = ResourceNames.Campaign(customerId, campaignId); // Creates the campaign label. CampaignLabel campaignLabel = new CampaignLabel() { Campaign = campaignResourceName, Label = labelResourceName }; operations.Add(new CampaignLabelOperation() { Create = campaignLabel }); } // Send the operation in a mutate request. try { MutateCampaignLabelsResponse response = campaignLabelService.MutateCampaignLabels(customerId.ToString(), operations); Console.WriteLine($"Added {response.Results} campaign labels:"); foreach (MutateCampaignLabelResult result in response.Results) { Console.WriteLine(result.ResourceName); } } 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, array $campaignIds, int $labelId ) { // Gets the resource name of the label to be added across all given campaigns. $labelResourceName = ResourceNames::forLabel($customerId, $labelId); // Creates a campaign label operation for each campaign. $operations = []; foreach ($campaignIds as $campaignId) { // Creates the campaign label. $campaignLabel = new CampaignLabel([ 'campaign' => ResourceNames::forCampaign($customerId, $campaignId), 'label' => $labelResourceName ]); $campaignLabelOperation = new CampaignLabelOperation(); $campaignLabelOperation->setCreate($campaignLabel); $operations[] = $campaignLabelOperation; } // Issues a mutate request to add the labels to the campaigns. $campaignLabelServiceClient = $googleAdsClient->getCampaignLabelServiceClient(); $response = $campaignLabelServiceClient->mutateCampaignLabels( MutateCampaignLabelsRequest::build($customerId, $operations) ); printf("Added %d campaign labels:%s", $response->getResults()->count(), PHP_EOL); foreach ($response->getResults() as $addedCampaignLabel) { /** @var CampaignLabel $addedCampaignLabel */ printf( "New campaign label added with resource name: '%s'.%s", $addedCampaignLabel->getResourceName(), PHP_EOL ); } }
Python
def main(client, customer_id, label_id, campaign_ids): """This code example adds a campaign label to a list of campaigns. Args: client: An initialized GoogleAdsClient instance. customer_id: A client customer ID str. label_id: The ID of the label to attach to campaigns. campaign_ids: A list of campaign IDs to which the label will be added. """ # Get an instance of CampaignLabelService client. campaign_label_service = client.get_service("CampaignLabelService") campaign_service = client.get_service("CampaignService") label_service = client.get_service("LabelService") # Build the resource name of the label to be added across the campaigns. label_resource_name = label_service.label_path(customer_id, label_id) operations = [] for campaign_id in campaign_ids: campaign_resource_name = campaign_service.campaign_path( customer_id, campaign_id ) campaign_label_operation = client.get_type("CampaignLabelOperation") campaign_label = campaign_label_operation.create campaign_label.campaign = campaign_resource_name campaign_label.label = label_resource_name operations.append(campaign_label_operation) response = campaign_label_service.mutate_campaign_labels( customer_id=customer_id, operations=operations ) print(f"Added {len(response.results)} campaign labels:") for result in response.results: print(result.resource_name)
Ruby
def add_campaign_label(customer_id, label_id, campaign_ids) # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new label_resource_name = client.path.label(customer_id, label_id) labels = campaign_ids.map { |campaign_id| client.resource.campaign_label do |label| campaign_resource_name = client.path.campaign(customer_id, campaign_id) label.campaign = campaign_resource_name label.label = label_resource_name end } ops = labels.map { |label| client.operation.create_resource.campaign_label(label) } response = client.service.campaign_label.mutate_campaign_labels( customer_id: customer_id, operations: ops, ) response.results.each do |result| puts("Created campaign label with id: #{result.resource_name}") end end
Perl
sub add_campaign_labels { my ($api_client, $customer_id, $campaign_ids, $label_id) = @_; my $label_resource_name = Google::Ads::GoogleAds::V16::Utils::ResourceNames::label($customer_id, $label_id); my $campaign_label_operations = []; # Create a campaign label operation for each campaign. foreach my $campaign_id (@$campaign_ids) { # Create a campaign label. my $campaign_label = Google::Ads::GoogleAds::V16::Resources::CampaignLabel->new({ campaign => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign( $customer_id, $campaign_id ), label => $label_resource_name }); # Create a campaign label operation. my $campaign_label_operation = Google::Ads::GoogleAds::V16::Services::CampaignLabelService::CampaignLabelOperation ->new({ create => $campaign_label }); push @$campaign_label_operations, $campaign_label_operation; } # Add the campaign labels to the campaigns. my $campaign_labels_response = $api_client->CampaignLabelService()->mutate({ customerId => $customer_id, operations => $campaign_label_operations }); my $campaign_label_results = $campaign_labels_response->{results}; printf "Added %d campaign labels:\n", scalar @$campaign_label_results; foreach my $campaign_label_result (@$campaign_label_results) { printf "Created campaign label '%s'.\n", $campaign_label_result->{resourceName}; } return 1; }
ラベルを使ってオブジェクトを取得する
キャンペーンにラベルを割り当てたら、ラベル フィールドを使用して ID でオブジェクトを取得できます。
適切な GAQL クエリを GoogleAdsService
Search
または SearchStream
リクエストに渡します。たとえば、次のクエリは、3 つのラベル ID のいずれかに関連付けられているキャンペーンの ID、名前、ラベルを返します。
SELECT
campaign.id,
campaign.name,
label.id,
label.name
FROM campaign_label
WHERE label.id IN (123456, 789012, 345678)
フィルタできるのはラベル ID のみで、ラベル名でフィルタすることはできません。ラベル名からラベル ID を取得するには、次のクエリを使用します。
SELECT
label.id,
label.name
FROM label
WHERE label.name = "LABEL_NAME"
顧客に適用されたラベルを取得する
MCC アカウントのアカウントの階層を取得する場合、CustomerClient
オブジェクトから applied_labels
フィールドをリクエストすることで、子アカウントに適用されているラベルのリストを取得できます。このフィールドは、API 呼び出しを行ったユーザーが所有するラベルのみを取得します。
レポートでラベルを使用する
ラベルのレポート
ラベル レポート リソースは、アカウントで定義されたラベルの詳細を返します。詳細には、名前、ID、リソース名、ステータス、背景色、説明、ラベルの所有者を表す顧客リソースが含まれます。
指標付きのレポート
[広告グループ] と [キャンペーン] のレポートビューには、labels
フィールドが含まれています。レポート サービスは、ラベルリソース名を customers/{customer_id}/labels/{label_id}
の形式で返します。たとえば、リソース名 customers/123456789/labels/012345
は、ID 123456789
のアカウントにある ID 012345
のラベルを参照します。
指標のないレポート
次の各レポート リソースを使用して、リソースとラベルの関係を確認できます。
任意の数値比較演算子、または BETWEEN
、IS NULL
、IS NOT NULL
、IN
、NOT IN
演算子を使用して label.id
フィールドを比較することで、上記のレポート結果をフィルタリングできます。
たとえば、次のように、特定のラベル ID を持つすべてのキャンペーンを取得できます。
SELECT
campaign.id,
campaign.name,
label.id,
label.name
FROM campaign_label
WHERE label.id = LABEL_ID
ORDER BY campaign.id