Ярлыки

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

В этом руководстве рассматриваются следующие темы:

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

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

Примеры использования

Вот типичные сценарии использования ярлыков:

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

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

Создайте ярлыки, используя объект Label с заданным полем text_label:

1. Создайте экземпляр TextLabel, содержащий цвет фона и описание.
2. Создайте экземпляр Label и назначьте TextLabel его полю text_label.
3. Оберните Label в LabelOperation (create) и отправьте в LabelService.MutateLabels.

Запишите идентификатор созданного ярлыка для последующих запросов. Идентификатор встроен в поле resource_name в объекте MutateLabelResult, который возвращается в ответе MutateLabelsResponse.

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

Добавление ярлыков

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

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

• label: название ресурса ярлыка (например, customers/{customer_id}/labels/{label_id}).
• campaign – название ресурса кампании (например, customers/{customer_id}/campaigns/{campaign_id}).

Создайте экземпляр CampaignLabel для каждой пары "ярлык – кампания". Оберните его в CampaignLabelOperation с операцией create и отправьте в CampaignLabelService.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());
    }
  }
}
AddCampaignLabels.java
      

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;
    }
}
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
      

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

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

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

curl

Примечание. Здесь не приведен пример кода REST для этого шага, но вы можете выполнить его с помощью запроса REST вручную.

Ознакомьтесь с документацией по REST-интерфейсу Google Ads API и справочными страницами по методам. Вам нужно будет создать полезную нагрузку JSON на основе определений proto.

Полезные ресурсы:

• Использование REST
• Структура интерфейса REST
• Сопоставление полей JSON
• Информацию о конкретном сервисе и методе можно найти в Справке по REST API.

Как назначить ярлыки клиентам

Назначение ярлыков клиенту – это обычная задача для управляющих аккаунтов, позволяющая классифицировать клиентские аккаунты. Это делается с помощью CustomerLabelService. Ярлыки, созданные в управляющем аккаунте, принадлежат ему и видны только после аутентификации в нем.

Каждый объект CustomerLabelOperation включает экземпляр CustomerLabel. При создании связи между клиентом и ярлыком учитывайте следующее:

• label – обязательное поле, в котором должно быть указано название ресурса ярлыка, принадлежащего аккаунту менеджера, например customers/{MANAGER_ID}/labels/{LABEL_ID}.
• customer. Это поле предназначено только для вывода, и его не нужно задавать в запросе. Клиент, которому присваивается ярлык, определяется по значению customer_id в пути MutateCustomerLabelsRequest.

Примечание. С помощью одного запроса MutateCustomerLabelsRequest можно изменить ярлыки только в одном клиентском аккаунте, указанном в запросе. Чтобы применить ярлык к нескольким клиентским аккаунтам, необходимо выполнить отдельные вызовы API для каждого аккаунта.

Получение объектов с помощью ярлыков

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

Передайте подходящий запрос 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.

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

Ярлыки помогают повысить информативность отчетов.

Отчеты о ярлыках

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

Отчеты с показателями

Представления отчетов Ad Group и Campaign содержат поле 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