Le etichette ti consentono di classificare campagne, gruppi di annunci, annunci e parole chiave e di utilizzare queste categorie per semplificare il flusso di lavoro in vari modi.
Questa guida illustra i passaggi necessari per:
- Crea etichette in modo programmatico utilizzando
LabelService. - Assegna etichette alle tue campagne utilizzando le richieste
CampaignLabelService. - Recupera e filtra i risultati dei report per etichetta utilizzando le query
GoogleAdsService.
Questa guida è incentrata sulle campagne, ma puoi utilizzare lo stesso approccio per gruppi di annunci, annunci e parole chiave. Questa API fornisce anche
CustomerLabelService, che consente
agli account amministratore di assegnare etichette agli account secondari.
Casi d'uso
Gli scenari tipici per l'utilizzo delle etichette includono quanto segue:
- Il tuo account contiene campagne che attivi solo in determinati periodi dell'anno e vuoi includerle o escluderle dai report.
- Hai aggiunto un nuovo insieme di parole chiave al gruppo di annunci e vuoi confrontare le relative statistiche con quelle di altre parole chiave nel gruppo di annunci.
- Gli utenti del tuo account Google Ads gestiscono ciascuno un sottoinsieme di campagne e vuoi un modo per identificare l'insieme di campagne per ogni utente.
- La tua app deve contrassegnare lo stato di determinati oggetti.
Crea etichette
Crea etichette utilizzando un oggetto Label con il relativo set di campi text_label:
- Crea un'istanza
TextLabelcontenente un colore di sfondo e una descrizione. - Crea un'istanza
Labele assegnaTextLabelal relativo campotext_label. - Inserisci
Labelin unLabelOperation(create) e invialo aLabelService.MutateLabels.
Prendi nota dell'ID dell'etichetta creata per le query successive. L'ID è incorporato nel campo
resource_name di
MutateLabelResult restituito in
MutateLabelsResponse.
Puoi anche utilizzare una richiesta GoogleAdsService Search
o SearchStream per recuperare gli ID etichetta e i nomi delle risorse.
Assegna etichette
Puoi assegnare etichette a campagne, clienti, gruppi di annunci, criteri o annunci
utilizzando l'operazione Mutate nel servizio corrispondente.
Ad esempio, per assegnare etichette a una campagna, passa uno o più oggetti
CampaignLabelOperation a
CampaignLabelService.MutateCampaignLabels. Ogni
CampaignLabelOperation include un'istanza
CampaignLabel, che richiede nomi
completi delle risorse in questi campi:
label: il nome della risorsa di un'etichetta (ad esempio,customers/{customer_id}/labels/{label_id}).campaign: il nome della risorsa di una campagna (ad esempio,customers/{customer_id}/campaigns/{campaign_id}).
Crea un'istanza di CampaignLabel per ogni coppia etichetta-campagna. Avvolgilo in un
CampaignLabelOperation con l'operazione create e invialo a
CampaignLabelService.MutateCampaignLabels.
Aggiungere etichette delle campagne
Ecco un esempio di codice che mostra come aggiungere un'etichetta campagna a un elenco di campagne:
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.V25.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: GoogleAdsClient, customer_id: str, label_id: str, campaign_ids: List[str], ) -> None: """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: CampaignLabelServiceClient = client.get_service( "CampaignLabelService" ) campaign_service: CampaignServiceClient = client.get_service( "CampaignService" ) label_service: LabelServiceClient = client.get_service("LabelService") # Build the resource name of the label to be added across the campaigns. label_resource_name: str = label_service.label_path(customer_id, label_id) operations: List[Any] = [] for campaign_id in campaign_ids: campaign_resource_name: str = campaign_service.campaign_path( customer_id, campaign_id ) campaign_label_operation: Any = client.get_type( "CampaignLabelOperation" ) campaign_label: CampaignLabel = campaign_label_operation.create campaign_label.campaign = campaign_resource_name campaign_label.label = label_resource_name operations.append(campaign_label_operation) response: MutateCampaignLabelsResponse = ( 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::V25::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::V25::Resources::CampaignLabel->new({ campaign => Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign( $customer_id, $campaign_id ), label => $label_resource_name }); # Create a campaign label operation. my $campaign_label_operation = Google::Ads::GoogleAds::V25::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; }
curl
Assegnare etichette ai clienti
L'assegnazione di etichette a un cliente è un'attività comune per gli account amministratore per
categorizzare i propri account cliente. Questa operazione viene eseguita utilizzando
CustomerLabelService. Le etichette create da
un account amministratore sono di proprietà di quell'account amministratore e sono visibili solo quando
l'autenticazione viene eseguita come account amministratore proprietario.
Ogni CustomerLabelOperation include un'istanza CustomerLabel. Quando crei una relazione con un cliente, tieni presente che:
label: questo campo è obbligatorio e deve essere il nome della risorsa di un'etichetta di proprietà dell'account amministratore, ad esempiocustomers/{MANAGER_ID}/labels/{LABEL_ID}.customer: questo campo è solo di output e non deve essere impostato nella richiesta. Il cliente etichettato è determinato dacustomer_idnel percorsoMutateCustomerLabelsRequest.
Recuperare gli oggetti utilizzando le relative etichette
Dopo aver assegnato le etichette alle campagne, puoi utilizzare i campi delle etichette per recuperare gli oggetti in base all'ID.
Passa una query GAQL appropriata a una richiesta
GoogleAdsService Search o SearchStream. Ad esempio, la seguente query restituisce l'ID, il nome e le etichette per
ogni campagna associata a uno dei tre ID etichetta:
SELECT
campaign.id,
campaign.name,
label.id,
label.name
FROM campaign_label
WHERE label.id IN (123456, 789012, 345678)
Puoi filtrare solo in base all'ID etichetta, non al nome dell'etichetta. Per ottenere l'ID etichetta da un nome di etichetta, utilizza questa query:
SELECT
label.id,
label.name
FROM label
WHERE label.name = "LABEL_NAME"
Recuperare le etichette applicate a un cliente
Quando recuperi la gerarchia degli account di un account amministratore,
puoi recuperare l'elenco delle etichette applicate a un account cliente secondario
richiedendo il campo applied_labels dall'oggetto
CustomerClient. Questo campo recupera
solo le etichette di proprietà del cliente che esegue la chiamata API.
Utilizzare le etichette nei report
Utilizza le etichette per migliorare l'utilità dei report.
Report sulle etichette
La risorsa report Etichetta restituisce dettagli sulle etichette definite in un account. I dettagli includono nome, ID, nome risorsa, stato, colore di sfondo e descrizione, nonché la risorsa Customer che rappresenta il proprietario dell'etichetta.
Report con metriche
Le visualizzazioni dei report Gruppo di annunci e Campagna
contengono il campo labels. Il servizio di generazione dei report restituisce i nomi delle risorse delle etichette nel formato customers/{customer_id}/labels/{label_id}. Ad esempio, il nome della risorsa customers/123456789/labels/012345 si riferisce
all'etichetta con ID 012345 nell'account con ID 123456789.
Report senza metriche
Ciascuna delle seguenti risorse per i report può essere utilizzata per trovare relazioni tra risorse ed etichette:
- Etichetta annuncio gruppo di annunci
- Etichetta criterio del gruppo di annunci
- Etichetta gruppo di annunci
- Etichetta campagna
- Etichetta cliente
Puoi filtrare i risultati di questi report confrontando il campo label.id utilizzando qualsiasi operatore di confronto numerico o gli operatori BETWEEN, IS NULL, IS NOT NULL, IN o NOT IN.
In questo esempio, puoi ottenere tutte le campagne con un ID etichetta specifico:
SELECT
campaign.id,
campaign.name,
label.id,
label.name
FROM campaign_label
WHERE label.id = LABEL_ID
ORDER BY campaign.id