Crea grupos de fichas de hotel

Los grupos de anuncios de hoteles admiten la división de tus hoteles en muchos grupos de fichas de hoteles en varias dimensiones para que puedas ajustar las ofertas de cada grupo según corresponda. Considera el siguiente árbol, en el que, en el primer nivel, los hoteles se dividieron en hoteles de 5 estrellas, hoteles de 4 estrellas y otras categorías de hoteles. En el segundo nivel, los hoteles de otras categorías se dividieron en hoteles de Estados Unidos, hoteles del Reino Unido y hoteles de otras regiones.

Cada nodo del árbol es una subdivisión o una unidad, según se define en ListingGroupType. Una subdivisión introduce un nuevo nivel en el árbol, mientras que las unidades son hojas del árbol. Cada subdivisión siempre debe estar completamente dividida, por lo que debe contener un nodo que represente Otro. En el ejemplo, los nodos raíz y Categoría de hotel: (Otro) son subdivisiones. Esta estructura de árbol con subdivisiones y unidades te permite establecer ofertas a nivel de la unidad y garantiza que cada ficha de hotel se encuentre en un solo nodo de unidad en el árbol.

Los nodos son objetos de la clase ListingGroupInfo, que contiene el campo ListingGroupType que indica si los nodos son unidades o subdivisiones. Si configuras ListingGroupInfo en listing_group de AdGroupCriterion, se vincula a la AdGroup.

Punto clave: Necesitas al menos un nodo de unidad para que un árbol sea válido. Los anuncios de hoteles no se publican hasta que creas un árbol de grupos de fichas válido.

Cómo establecer ofertas de CPC porcentual

Puedes establecer ofertas (como percent_cpc_bid_micros o cpc_bid_micros, según tu estrategia de ofertas) en AdGroupCriterion solo para los nodos de unidad. Si intentas establecer ofertas en nodos de subdivisión, se produce un error.

Dimensiones para los grupos de fichas de hoteles

Un ListingGroupInfo también tiene un case_value, que es un ListingDimensionInfo que contiene uno de varios tipos de dimensiones. Un ListingGroupInfo representa los valores asociados con tus hoteles, como el ID del hotel, el país del hotel o la categoría del hotel. En la ListingDimensionInfo documentación de referencia de ListingDimensionInfo, se incluye una descripción completa de los tipos de ListingDimensionInfo disponibles.

Cada elemento secundario inmediato de una subdivisión debe tener un case_value del mismo subtipo ListingDimensionInfo. Solo el nodo raíz no tiene un case_value.

Recuerda que cada subdivisión debe contener un case_value vacío del tipo correcto, que represente todos los valores Otro.

Para obtener más detalles, consulta el siguiente fragmento de código, que agrega el primer nivel del árbol de grupos de fichas:

Java

private static String addLevel1Nodes(
    long customerId,
    long adGroupId,
    String rootResourceName,
    List<AdGroupCriterionOperation> operations,
    long percentCpcBidMicroAmount) {
  // Creates hotel class info and dimension info for 5-star hotels.
  ListingDimensionInfo fiveStarredDimensionInfo =
      ListingDimensionInfo.newBuilder()
          .setHotelClass(HotelClassInfo.newBuilder().setValue(5).build())
          .build();
  // Creates listing group info for 5-star hotels as a UNIT node.
  ListingGroupInfo fiveStarredUnit =
      ListingGroupInfo.newBuilder()
          .setType(ListingGroupType.UNIT)
          .setParentAdGroupCriterion(rootResourceName)
          .setCaseValue(fiveStarredDimensionInfo)
          .build();
  // Creates an ad group criterion for 5-star hotels.
  AdGroupCriterion fiveStarredAdGroupCriterion =
      createAdGroupCriterion(customerId, adGroupId, fiveStarredUnit, percentCpcBidMicroAmount);
  // Decrements the temp ID for the next ad group criterion.
  AdGroupCriterionOperation operation = generateCreateOperation(fiveStarredAdGroupCriterion);
  operations.add(operation);

  // You can also create more UNIT nodes for other hotel classes by copying the above code in
  // this method and modifying the value passed to HotelClassInfo() to the value you want.
  // For instance, passing 4 instead of 5 in the above code will create a UNIT node of 4-star
  // hotels instead.

  // Creates hotel class info and dimension info for other hotel classes by not specifying
  // any attributes on those object.
  ListingDimensionInfo otherHotelsDimensionInfo =
      ListingDimensionInfo.newBuilder()
          .setHotelClass(HotelClassInfo.newBuilder().build())
          .build();
  // Creates listing group info for other hotel classes as a SUBDIVISION node, which will be
  // used as a parent node for children nodes of the next level.
  ListingGroupInfo otherHotelsSubdivision =
      createListingGroupInfo(
          ListingGroupType.SUBDIVISION, rootResourceName, otherHotelsDimensionInfo);
  // Creates an ad group criterion for other hotel classes.
  AdGroupCriterion otherHotelsAdGroupCriterion =
      createAdGroupCriterion(
          customerId, adGroupId, otherHotelsSubdivision, percentCpcBidMicroAmount);
  operation = generateCreateOperation(otherHotelsAdGroupCriterion);
  operations.add(operation);

  return otherHotelsAdGroupCriterion.getResourceName();
}
AddHotelListingGroupTree.java
      

C#

private string AddLevel1Nodes(long customerId, long adGroupId, string rootResourceName,
    List<AdGroupCriterionOperation> operations, long percentCpcBidMicroAmount)
{
    // Create listing dimension info for 5-star class hotels.
    ListingDimensionInfo fiveStarredListingDimensionInfo = new ListingDimensionInfo
    {
        HotelClass = new HotelClassInfo
        {
            Value = 5
        }
    };

    // Create a listing group info for 5-star hotels as a UNIT node.
    ListingGroupInfo fiveStarredUnit = CreateListingGroupInfo(ListingGroupType.Unit,
        rootResourceName, fiveStarredListingDimensionInfo);

    // Create an ad group criterion for 5-star hotels.
    AdGroupCriterion fiveStarredAdGroupCriterion = CreateAdGroupCriterion(customerId,
        adGroupId, fiveStarredUnit, percentCpcBidMicroAmount);

    // Create an operation and add it to the list of operations.
    operations.Add(new AdGroupCriterionOperation
    {
        Create = fiveStarredAdGroupCriterion
    });

    // Decrement the temp ID for the next ad group criterion.
    nextTempId--;

    // You can also create more UNIT nodes for other hotel classes by copying the above code
    // in this method and modifying the value passed to HotelClassInfo().
    // For instance, passing 4 instead of 5 in the above code will instead create a UNIT
    // node of 4-star hotels.

    // Create hotel class info and dimension info for other hotel classes by *not*
    // specifying any attributes on those object.
    ListingDimensionInfo otherHotelsListingDimensionInfo = new ListingDimensionInfo
    {
        HotelClass = new HotelClassInfo()
    };

    // Create listing group info for other hotel classes as a SUBDIVISION node, which will
    // be used as a parent node for children nodes of the next level.
    ListingGroupInfo otherHotelsSubdivisionListingGroupInfo = CreateListingGroupInfo
        (ListingGroupType.Subdivision, rootResourceName, otherHotelsListingDimensionInfo);

    // Create an ad group criterion for other hotel classes.
    AdGroupCriterion otherHotelsAdGroupCriterion = CreateAdGroupCriterion(customerId,
        adGroupId, otherHotelsSubdivisionListingGroupInfo, percentCpcBidMicroAmount);

    // Create an operation and add it to the list of operations.
    operations.Add(new AdGroupCriterionOperation
    {
        Create = otherHotelsAdGroupCriterion
    });

    // Decrement the temp ID for the next ad group criterion.
    nextTempId--;

    return otherHotelsAdGroupCriterion.ResourceName;
}
AddHotelListingGroupTree.cs
      

PHP

private static function addLevel1Nodes(
    int $customerId,
    int $adGroupId,
    string $rootResourceName,
    array &$operations,
    int $percentCpcBidMicroAmount
) {
    // Creates hotel class info and dimension info for 5-star hotels.
    $fiveStarredDimensionInfo = new ListingDimensionInfo(
        [
        'hotel_class' => new HotelClassInfo(['value' => 5])
        ]
    );
    // Creates listing group info for 5-star hotels as a UNIT node.
    $fiveStarredUnit = self::createListingGroupInfo(
        ListingGroupType::UNIT,
        $rootResourceName,
        $fiveStarredDimensionInfo
    );
    // Creates an ad group criterion for 5-star hotels.
    $fiveStarredAdGroupCriterion = self::createAdGroupCriterion(
        $customerId,
        $adGroupId,
        $fiveStarredUnit,
        $percentCpcBidMicroAmount
    );
    // Decrements the temp ID for the next ad group criterion.
    self::$nextTempId--;
    $operation = self::generateCreateOperation($fiveStarredAdGroupCriterion);
    $operations[] = $operation;

    // You can also create more UNIT nodes for other hotel classes by copying the above code in
    // this method and modifying the value passed to HotelClassInfo() to the value you want.
    // For instance, passing 4 instead of 5 in the above code will create a UNIT node of 4-star
    // hotels instead.

    // Creates hotel class info and dimension info for other hotel classes by *not* specifying
    // any attributes on those object.
    $othersHotelsDimensionInfo = new ListingDimensionInfo(
        [
        'hotel_class' => new HotelClassInfo()
        ]
    );
    // Creates listing group info for other hotel classes as a SUBDIVISION node, which will be
    // used as a parent node for children nodes of the next level.
    $otherHotelsSubDivision = self::createListingGroupInfo(
        ListingGroupType::SUBDIVISION,
        $rootResourceName,
        $othersHotelsDimensionInfo
    );
    // Creates an ad group criterion for other hotel classes.
    $otherHotelsAdGroupCriterion = self::createAdGroupCriterion(
        $customerId,
        $adGroupId,
        $otherHotelsSubDivision,
        $percentCpcBidMicroAmount
    );
    $operation = self::generateCreateOperation($otherHotelsAdGroupCriterion);
    $operations[] = $operation;

    self::$nextTempId--;
    return $otherHotelsAdGroupCriterion->getResourceName();
}
AddHotelListingGroupTree.php
      

Python

def add_level1_nodes(
    client: GoogleAdsClient,
    customer_id: str,
    ad_group_id: str,
    root_resource_name: str,
    operations: List[AdGroupCriterionOperation],
    percent_cpc_bid_micro_amount: int,
) -> str:
    """Creates child nodes on level 1, partitioned by the hotel class info.

    Args:
        client: The Google Ads API client.
        customer_id: The Google Ads customer ID.
        ad_group_id: The ad group ID to which the hotel listing group will be
            added.
        root_resource_name: The string resource name of the listing group's root
            node.
        operations: A list of AdGroupCriterionOperations.
        percent_cpc_bid_micro_amount: The CPC bid micro amount to be set on
            created ad group criteria.

    Returns:
        The string resource name of the "other hotel classes" node, which serves
        as the parent node for the next level of the listing tree.
    """
    global next_temp_id

    # Create listing dimension info for 5-star class hotels.
    five_starred_listing_dimension_info: ListingDimensionInfo = client.get_type(
        "ListingDimensionInfo"
    )
    five_starred_listing_dimension_info.hotel_class.value = 5

    # Create a listing group info for 5-star hotels as a UNIT node.
    five_starred_unit: ListingGroupInfo = create_listing_group_info(
        client,
        client.enums.ListingGroupTypeEnum.UNIT,
        root_resource_name,
        five_starred_listing_dimension_info,
    )

    # Create an ad group criterion for 5-star hotels.
    five_starred_ad_group_criterion: AdGroupCriterion = (
        create_ad_group_criterion(
            client,
            customer_id,
            ad_group_id,
            five_starred_unit,
            percent_cpc_bid_micro_amount,
        )
    )

    # Create an operation and add it to the list of operations.
    five_starred_ad_group_criterion_operation: AdGroupCriterionOperation = (
        client.get_type("AdGroupCriterionOperation")
    )
    client.copy_from(
        five_starred_ad_group_criterion_operation.create,
        five_starred_ad_group_criterion,
    )
    operations.append(five_starred_ad_group_criterion_operation)

    # Decrement the temp ID for the next ad group criterion.
    next_temp_id -= 1

    # You can also create more UNIT nodes for other hotel classes by copying the
    # above code in this method and modifying the hotel class value.
    # For instance, passing 4 instead of 5 in the above code will instead create
    # a UNIT node of 4-star hotels.

    # Create hotel class info and dimension info without any specifying
    # attributes. This node will then represent hotel classes other than those
    # already covered by UNIT nodes at this level.
    other_hotels_listing_dimension_info: ListingDimensionInfo = client.get_type(
        "ListingDimensionInfo"
    )
    # Set "hotel_class" as the oneof field on the ListingDimensionInfo object
    # without specifying the optional hotel_class field.
    client.copy_from(
        other_hotels_listing_dimension_info.hotel_class,
        client.get_type("HotelClassInfo"),
    )

    # Create listing group info for other hotel classes as a SUBDIVISION node,
    # which will be used as a parent node for children nodes of the next level.
    other_hotels_subdivision_listing_group_info: ListingGroupInfo = (
        create_listing_group_info(
            client,
            client.enums.ListingGroupTypeEnum.SUBDIVISION,
            root_resource_name,
            other_hotels_listing_dimension_info,
        )
    )

    # Create an ad group criterion for other hotel classes.
    other_hotels_ad_group_criterion: AdGroupCriterion = (
        create_ad_group_criterion(
            client,
            customer_id,
            ad_group_id,
            other_hotels_subdivision_listing_group_info,
            percent_cpc_bid_micro_amount,
        )
    )

    # Create an operation and add it to the list of operations.
    other_hotels_ad_group_criterion_operation: AdGroupCriterionOperation = (
        client.get_type("AdGroupCriterionOperation")
    )
    client.copy_from(
        other_hotels_ad_group_criterion_operation.create,
        other_hotels_ad_group_criterion,
    )
    operations.append(other_hotels_ad_group_criterion_operation)

    # Decrement the temp ID for the next ad group criterion.
    next_temp_id -= 1

    return other_hotels_ad_group_criterion.resource_name
add_hotel_listing_group_tree.py
      

Ruby

def add_level1_nodes(
  client,
  customer_id,
  ad_group_id,
  root_resource_name,
  operations,
  percent_cpc_bid_micro_amount)
  # Creates hotel class info and dimension info for 5-star hotels.
  five_starred_dimension_info = client.resource.listing_dimension_info do |d|
    d.hotel_class = client.resource.hotel_class_info do |c|
      c.value = 5
    end
  end

  # Creates listing group info for 5-star hotels as a UNIT node.
  five_starred_unit = create_listing_group_info(
    client,
    :UNIT,
    root_resource_name,
    five_starred_dimension_info,
  )

  # Creates an ad group criterion for 5-star hotels.
  five_starred_ad_group_criterion = create_ad_group_criterion(
    client,
    customer_id,
    ad_group_id,
    five_starred_unit,
    percent_cpc_bid_micro_amount,
  )

  operations << generate_create_operation(
    client,
    five_starred_ad_group_criterion,
  )

  # You can also create more UNIT nodes for other hotel classes by copying the
  # above code in this method and modifying the value passed to HotelClassInfo()
  # to the value you want.
  # For instance, passing 4 instead of 5 in the above code will create a UNIT
  # node of 4-star hotels instead.

  # Creates hotel class info and dimension info for other hotel classes
  # by *not* specifying any attributes on those object.
  other_hotels_dimention_info = client.resource.listing_dimension_info do |d|
    d.hotel_class = client.resource.hotel_class_info
  end

  # Creates listing group info for other hotel classes as a SUBDIVISION node,
  # which will be used as a parent node for children nodes of the next level.
  other_hotels_subdivision = create_listing_group_info(
    client,
    :SUBDIVISION,
    root_resource_name,
    other_hotels_dimention_info,
  )

  # Creates an ad group criterion for other hotel classes.
  other_hotels_ad_group_criterion = create_ad_group_criterion(
    client,
    customer_id,
    ad_group_id,
    other_hotels_subdivision,
    percent_cpc_bid_micro_amount,
  )

  operations << generate_create_operation(
    client,
    other_hotels_ad_group_criterion,
  )

  other_hotels_ad_group_criterion.resource_name
end
add_hotel_listing_group_tree.rb
      

Perl

sub add_level_1_nodes {
  my ($customer_id, $ad_group_id, $root_resource_name, $operations,
    $percent_cpc_bid_micro_amount)
    = @_;

  # Create hotel class info and dimension info for 5-star hotels.
  my $five_starred_dimension_info =
    Google::Ads::GoogleAds::V26::Common::ListingDimensionInfo->new({
      hotelClass => Google::Ads::GoogleAds::V26::Common::HotelClassInfo->new({
          value => 5
        })});

  # Create listing group info for 5-star hotels as a UNIT node.
  my $five_starred_unit = create_listing_group_info(UNIT, $root_resource_name,
    $five_starred_dimension_info);

  # Create an ad group criterion for 5-star hotels.
  my $five_starred_ad_group_criterion =
    create_ad_group_criterion($customer_id, $ad_group_id, $five_starred_unit,
    $percent_cpc_bid_micro_amount);

  my $operation = generate_create_operation($five_starred_ad_group_criterion);
  push @$operations, $operation;

  # You can also create more UNIT nodes for other hotel classes by copying the
  # above code in this method and modifying the value passed to HotelClassInfo
  # to the value you want. For instance, passing 4 instead of 5 in the above code
  #  will create a UNIT node of 4-star hotels instead.

  # Create hotel class info and dimension info for other hotel classes by *not*
  # specifying any attributes on those object.
  my $others_hotels_dimension_info =
    Google::Ads::GoogleAds::V26::Common::ListingDimensionInfo->new({
      hotelClass => Google::Ads::GoogleAds::V26::Common::HotelClassInfo->new()}
    );

  # Create listing group info for other hotel classes as a SUBDIVISION node, which
  # will be used as a parent node for children nodes of the next level.
  my $other_hotels_subdivision =
    create_listing_group_info(SUBDIVISION, $root_resource_name,
    $others_hotels_dimension_info);

  # Create an ad group criterion for other hotel classes.
  my $other_hotels_ad_group_criterion =
    create_ad_group_criterion($customer_id, $ad_group_id,
    $other_hotels_subdivision, $percent_cpc_bid_micro_amount);

  $operation = generate_create_operation($other_hotels_ad_group_criterion);
  push @$operations, $operation;

  return $other_hotels_ad_group_criterion->{resourceName};
}
add_hotel_listing_group_tree.pl
      

curl

Nota: Si bien aquí no se proporciona una muestra de código de REST directa para este paso, puedes lograrlo con una solicitud de REST manual.

Consulta la documentación de la interfaz de REST de la API de Google Ads y las páginas de referencia específicas del método. Deberás construir la carga útil JSON en función de las definiciones de proto.

Recursos clave:

• Uso de REST
• Estructura de la interfaz de REST
• Asignaciones de campos JSON
• Consulta la referencia de la API de REST para obtener información sobre el servicio y el método específicos.

Dimensiones disponibles para ListingDimensionInfo

Los siguientes tipos de ListingDimensionInfo están disponibles para los anuncios de hoteles:

• HotelIdInfo
• HotelClassInfo
• HotelCountryRegionInfo
• HotelStateInfo
• HotelCityInfo

Sugerencia: Para crear nodos de unidad Otro , pasa un objeto vacío de ListingDimensionInfo tipos a ListingGroupInfo. También debes establecer el campo de oferta (como percent_cpc_bid_micros) en el AdGroupCriterion de un Otro nodo de unidad.

IDs temporales

A los criterios del grupo de anuncios no se les asignan IDs hasta que el servidor procesa la solicitud de mutación que los crea. Sin embargo, un ListingGroupInfo no es válido hasta que se completa, por lo que, cada vez que creas una subdivisión, también debes crear al menos uno de sus elementos secundarios en la misma operación.

Para establecer el parent_ad_group_criterion de ListingGroupInfo para los nodos secundarios, puedes usar IDs de criterio temporales. Estos son identificadores únicos a nivel local (en lugar de global) que se aplican solo en el contexto de una sola solicitud de mutación. Se puede usar cualquier número entero negativo único (por ejemplo, -1, -2, -3) como ID temporal dentro de una sola solicitud.

Cuando se procesa la solicitud, a cada AdGroupCriterion se asigna un ID global positivo como de costumbre.