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

Этикетки

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

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

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

This guide focuses on campaigns, but you can use the same approach for ad groups, ads, and keywords. This API also provides CustomerLabelService , which enables manager accounts to assign labels to child accounts.

Варианты использования

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

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

Создать метки

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

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

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

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

Присвоить метки

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

For example, to assign labels to a campaign, pass one or more CampaignLabelOperation objects to CampaignLabelService.MutateCampaignLabels . Each CampaignLabelOperation includes a CampaignLabel instance, which requires full resource names in these fields:

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

Руби

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

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

локон

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

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

Основные ресурсы:

Использование REST
Структура REST-интерфейса
Сопоставление полей JSON
Для получения информации о конкретном сервисе и методе обратитесь к справочнику REST API .

Присвойте метки клиентам

Assigning labels to a customer is a common task for manager accounts to categorize their client accounts. This is performed using CustomerLabelService . Labels created by a manager account are owned by that manager account and are visible only when authenticated as the owning manager account.

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

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

Извлекайте объекты, используя их метки.

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

Pass an appropriate GAQL query to a GoogleAdsService Search or SearchStream request. For example, the following query returns the ID, name, and labels for each campaign associated with any one of three label IDs:

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

Фильтрация возможна только по идентификатору метки (ID), а не по названию метки (Name). Чтобы получить идентификатор метки из названия метки, используйте следующий запрос:

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

Получить этикетки, наклеенные на клиента.

When getting the hierarchy of accounts under a manager account , you can retrieve the list of labels applied to a child customer account by requesting the applied_labels field from the CustomerClient object. This field retrieves only the labels owned by the customer making the API call.

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

Используйте метки, чтобы повысить полезность ваших отчетов.

Сообщения о маркировке

The Label report resource returns details about the labels defined in an account. Details include the name, ID, resource name, status, background color, and description, as well as the Customer resource representing the label's owner.

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

The Ad Group and Campaign report views contain the labels field. The reporting service returns the label resource names in the format customers/{customer_id}/labels/{label_id} . For example, the resource name customers/123456789/labels/012345 refers to the label with ID 012345 in the account with ID 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

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

Потоковое