Etichette

Le etichette ti consentono di classificare le campagne, i gruppi di annunci, gli annunci e le parole chiave e di utilizzare queste categorie per semplificare il flusso di lavoro in diversi modi.

Questa guida illustra i passaggi necessari per:

  • Crea le etichette in modo programmatico utilizzando LabelService.
  • Assegna le etichette alle campagne utilizzando le richieste CampaignLabelService.
  • Recupera e filtra i risultati dei report in base all'etichetta utilizzando le query GoogleAdsService.

Questa guida è incentrata sulle campagne, ma puoi utilizzare lo stesso approccio per gruppi di annunci, annunci e parole chiave. Tieni presente che l'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 sono i seguenti:

  • Il tuo account contiene campagne che attivi solo in determinati periodi dell'anno e vuoi includerle o escluderle facilmente 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 identificare l'insieme di campagne per ciascun utente.
  • L'app deve contrassegnare lo stato di determinati oggetti.

Crea etichette

Crea etichette con l'oggetto TextLabel:

  1. Crea un'istanza TextLabel.
  2. Imposta un colore di sfondo per questo TextLabel.
  3. Inserisci il testo per questo TextLabel utilizzando il campo della descrizione.
  4. Inserisci il TextLabel in un LabelOperation e invialo a LabelService.MutateLabels.

Prendi nota degli ID delle nuove etichette per le query successive. Gli ID sono incorporati nel campo resource_name in MutateLabelResults restituito in MutateLabelsResponse.

Puoi anche utilizzare una richiesta LabelService.GetLabel o una richiesta GoogleAdsService Search o SearchStream per recuperare gli ID.

Assegnazione etichette

Puoi assegnare etichette a campagne, clienti, gruppi di annunci, criteri o annunci. Utilizza l'operazione Mutate nel servizio appropriato per assegnare le etichette.

Ad esempio, per assegnare le etichette a una campagna, passa uno o più CampaignLabelOperation a CampaignLabelService.MutateCampaignLabels. Ogni CampaignLabelOperation include un'istanza CampaignLabel, che contiene i seguenti campi:

  • label: ID di un'etichetta
  • campaign: ID di una campagna

Crea un'istanza di CampaignLabel per ogni coppia di etichetta e campagna. Inseriscilo in un CampaignLabelOperation con l'operazione create e invialo a CampaignService.MutateCampaignLabels.

Aggiungere etichette alle campagne

Ecco un esempio di codice che mostra come aggiungere un'etichetta campagna a un elenco di campagne:

JavaC#PHPPythonRubyPerl
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());
    }
  }
}
AddCampaignLabels.java

      
public void Run(GoogleAdsClient client, long customerId, long[] campaignIds, long labelId)
{
    // Get the CampaignLabelServiceClient.
    CampaignLabelServiceClient campaignLabelService =
        client.GetService(Services.V19.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;
    }
}
AddCampaignLabels.cs

      
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
        );
    }
}
AddCampaignLabels.php

      
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)
add_campaign_labels.py

      
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
add_campaign_labels.rb

      
sub add_campaign_labels {
  my ($api_client, $customer_id, $campaign_ids, $label_id) = @_;

  my $label_resource_name =
    Google::Ads::GoogleAds::V19::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::V19::Resources::CampaignLabel->new({
        campaign => Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
          $customer_id, $campaign_id
        ),
        label => $label_resource_name
      });

    # Create a campaign label operation.
    my $campaign_label_operation =
      Google::Ads::GoogleAds::V19::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;
}
add_campaign_labels.pl

Recuperare gli oggetti utilizzando le relative etichette

Dopo aver assegnato le etichette alle campagne, puoi utilizzare i campi etichetta per recuperare gli oggetti in base all'ID.

Passa una query GAQL appropriata a una richiesta Search o SearchStream.GoogleAdsService Ad esempio, la seguente query restituisce l'ID, il nome e le etichette di 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)

Tieni presente che puoi filtrare solo in base all'ID etichetta, non al nome dell'etichetta. Per ottenere l'ID dell'etichetta da un nome, puoi utilizzare questa query:

SELECT
  label.id,
  label.name
FROM label
WHERE label.name = "LABEL_NAME"

Recuperare le etichette applicate a un cliente

Quando ottieni 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 effettua la chiamata all'API.

Utilizzare le etichette nei report

Report sulle etichette

La risorsa report Etichetta restituisce i dettagli sulle etichette definite in un account. I dettagli includono nome, ID, nome della risorsa, stato, colore di sfondo e descrizione, nonché la risorsa Client 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 di report restituisce i nomi delle risorse dell'etichetta nel formato customers/{customer_id}/labels/{label_id}. Ad esempio, il nome della risorsa customers/123456789/labels/012345 fa riferimento all'etichetta con ID 012345 nell'account con ID 123456789.

Report senza metriche

Ogni una delle seguenti risorse report può essere utilizzata per trovare relazioni tra risorse ed etichette:

Puoi filtrare i risultati del report riportato sopra confrontando il campo label.id utilizzando qualsiasi operatore di confronto numerico o gli operatori BETWEEN, IS NULL, IS NOT NULL, IN o NOT IN.

Ad esempio, puoi ottenere tutte le campagne con un ID etichetta specifico come segue:

SELECT
  campaign.id,
  campaign.name,
  label.id,
  label.name
FROM campaign_label
WHERE label.id = LABEL_ID
ORDER BY campaign.id
Indietro
Nessuna metrica
Avanti
Streaming