Эта страница переведена с помощью Cloud Translation API.

Этикетки

Ярлыки позволяют классифицировать ваши кампании, группы объявлений, объявления и ключевые слова и использовать эти категории для упрощения рабочего процесса различными способами.

В этом руководстве описаны шаги, необходимые для выполнения следующих действий:

Создавайте этикетки программно с помощью LabelService .
Назначайте ярлыки своим кампаниям с помощью запросов CampaignLabelService .
Получайте и фильтруйте результаты отчета по меткам, используя запросы GoogleAdsService .

В этом руководстве основное внимание уделяется кампаниям, но вы можете использовать тот же подход для групп объявлений, объявлений и ключевых слов. Обратите внимание, что API также предоставляет CustomerLabelService , который позволяет управляющим учетным записям назначать метки дочерним учетным записям.

Случаи использования

Типичные сценарии использования меток включают следующее:

В вашей учетной записи есть кампании, которые вы включаете только в определенное время года, и вы хотите легко включать или исключать эти кампании из отчетов.
Вы добавили в группу объявлений новый набор ключевых слов и хотите сравнить их статистику с другими ключевыми словами в вашей группе объявлений.
Каждый из пользователей вашего аккаунта Google Рекламы управляет подмножеством кампаний, и вам нужен способ определить набор кампаний для каждого пользователя.
Вашему приложению необходимо отмечать статус определенных объектов.

Создание ярлыков

Создайте метки с помощью объекта TextLabel :

Создайте экземпляр TextLabel .
Установите цвет фона для этого TextLabel .
Введите текст для этой TextLabel используя поле описания.
Оберните TextLabel в LabelOperation и отправьте его в LabelService.MutateLabels .

Запишите идентификаторы новых ярлыков для последующих запросов. Идентификаторы встроены в поле resource_name в MutateLabelResults возвращаемом в MutateLabelsResponse .

Вы также можете использовать запрос LabelService.GetLabel или запрос GoogleAdsService Search или SearchStream для получения идентификаторов.

Назначать ярлыки

Вы можете назначать ярлыки своим кампаниям, клиентам, группам объявлений, критериям или объявлениям. Используйте операцию Mutate в соответствующем сервисе для назначения меток.

Например, чтобы назначить метки кампании, передайте одну или несколько CampaignLabelOperation в CampaignLabelService.MutateCampaignLabels . Каждая CampaignLabelOperation включает экземпляр CampaignLabel , который содержит следующие поля:

label : идентификатор метки
campaign : идентификатор кампании.

Создайте экземпляр CampaignLabel для каждой пары «ярлык-кампания». Оберните его в CampaignLabelOperation с операцией create и отправьте в CampaignService.MutateCampaignLabels .

Добавьте ярлыки кампании

Вот пример кода, показывающий, как добавить метку кампании в список кампаний:

Джава

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

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
        );
    }
}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
endadd_campaign_labels.rb

Перл

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;
}add_campaign_labels.pl

Извлечение объектов по их меткам

После того как вы присвоили метки своим кампаниям, вы можете использовать поля меток для извлечения объектов по идентификатору.

Передайте соответствующий запрос GAQL в запрос GoogleAdsService Search или SearchStream . Например, следующий запрос возвращает идентификатор, имя и метки для каждой кампании, связанной с любым из трех идентификаторов меток:

SELECT
  campaign.id,
  campaign.name,
  label.id,
  label.name
FROM campaign_label
WHERE label.id IN (123456, 789012, 345678)

Обратите внимание, что фильтровать можно только по идентификатору метки, а не по ее названию. Чтобы получить идентификатор метки из имени метки, вы можете использовать этот запрос:

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

Получение меток, примененных к клиенту

При получении иерархии учетных записей управляющего аккаунта вы можете получить список меток, примененных к дочерней учетной записи клиента, запросив поле applied_labels из объекта CustomerClient . Это поле извлекает только метки, принадлежащие клиенту, выполняющему вызов API.

Используйте ярлыки в отчетах

Отчеты по ярлыкам

Ресурс отчета «Метка» возвращает сведения о ярлыках, определенных в учетной записи. Подробные сведения включают имя, идентификатор, имя ресурса, статус, цвет фона и описание, а также ресурс «Клиент» , представляющий владельца метки.

Отчеты с метриками

Представления отчетов «Группа объявлений» и «Кампания» содержат поле labels . Служба отчетов возвращает имена ресурсов меток в формате customers/{customer_id}/labels/{label_id} . Например, имя ресурса customers/123456789/labels/012345 относится к метке с идентификатором 012345 в учетной записи с идентификатором 123456789 .

Отчеты без показателей

Каждый из следующих ресурсов отчета можно использовать для поиска связей между ресурсами и метками:

Вы можете отфильтровать приведенные выше результаты отчета, сравнив поле label.id с помощью любого числового оператора сравнения или операторов BETWEEN , IS NULL , IS NOT NULL , IN или NOT IN .

Например, вы можете получить все кампании с определенным идентификатором ярлыка следующим образом:

SELECT
  campaign.id,
  campaign.name,
  label.id,
  label.name
FROM campaign_label
WHERE label.id = LABEL_ID
ORDER BY campaign.id

Нулевые показатели

Потоковое