Información sobre el modelo de acceso de Google Ads

Existen dos tipos de cuentas de Google Ads: las cuentas de administrador de Google Ads y las cuentas de anunciante de Google Ads. Para obtener una explicación detallada de cómo se relacionan estos términos y otros (como Cuenta de cliente y Cliente), consulta Tipos de cuentas.

Las cuentas de administrador pueden administrar otras cuentas de administrador de Google Ads o cuentas de anunciante de Google Ads. Puedes vincular una cuenta de anunciante a una cuenta de administrador y luego administrar la cuenta de anunciante a través de la cuenta de administrador. La estructura vinculada general es un grafo acíclico dirigido con cuentas de anunciante en el nivel de hoja.

Puedes otorgar acceso a cuentas de Google Ads a usuarios individuales o cuentas de servicio. Existen dos formas de otorgar acceso a los usuarios a una cuenta de anunciante:

  • Invita al usuario a esa cuenta para otorgarle acceso directo a la cuenta de anunciante inviting them.
  • Invita al usuario a una cuenta de administrador vinculada a esa cuenta para otorgarle acceso indirecto a la cuenta de anunciante. El usuario obtiene acceso a la cuenta de anunciante, ya que la cuenta de administrador tiene acceso a todas las cuentas vinculadas a ella.

También puedes asignar funciones de usuario cuando invitas a un usuario a administrar una cuenta.

Considera la siguiente jerarquía de cuentas. Supongamos que todos los usuarios tienen acceso estándar.

Diagrama de una jerarquía de cuentas

En la siguiente tabla, se resume esta estructura de cuentas.

Usuario Tiene acceso directo a Tiene acceso indirecto a
U1, SA1 M1 M2, A1, A2, A3
U2 M2, M3 A1, A2, A3, A4
U3 A4  

ID de cliente de acceso

Un usuario puede tener acceso a varias jerarquías de cuentas. Cuando realizas una llamada a la API en esos casos, debes especificar la cuenta raíz que se usará para determinar correctamente los niveles de autorización y acceso a la cuenta. Para ello, especifica un encabezado login-customer-id como parte de la solicitud a la API.

En la siguiente tabla, se usa la jerarquía de cuentas del ejemplo anterior para mostrar qué IDs de cliente de acceso puedes usar y la lista correspondiente de cuentas a las que puedes realizar llamadas.

Usuario ID de cliente de acceso que se usará Cuentas a las que se realizarán llamadas a la API
U1, SA1 M1 M1, M2, A1, A2, A3
U2 M2 M2, A1, A2, A3
U2 M3 M3, A1, A4
U3 A4 A4

Puedes omitir el encabezado login-customer-id si el usuario tiene acceso directo a la cuenta de Google Ads a la que realizas llamadas. Por ejemplo, no es necesario que especifiques el encabezado login-customer-id cuando usas las credenciales U3 para realizar una llamada a A4, ya que los servidores de Google Ads pueden determinar correctamente el nivel de acceso a partir del ID de cliente (A4).

Si usas una de nuestras bibliotecas cliente, usa la siguiente configuración para especificar el encabezado login-customer-id.

Java

Agrega la siguiente configuración a tu archivo ads.properties.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

C#

Agrega la siguiente configuración cuando inicialices el objeto GoogleAdsConfig y lo uses para crear un objeto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    ...
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

PHP

Agrega la siguiente configuración a tu archivo google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Python

Agrega la siguiente configuración a tu archivo google-ads.yaml.

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

Ruby

Agrega la siguiente configuración a tu archivo google_ads_config.rb.

Google::Ads::GoogleAds::Config.new do |c|
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Crea una instancia de GoogleAdsClient pasando la ruta de acceso a la ubicación en la que guardas este archivo.

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Perl

Agrega la siguiente configuración a tu archivo googleads.properties.

loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

curl

Especifica el siguiente argumento de línea de comandos cuando ejecutes el comando curl.

-H "login-customer-id: LOGIN_CUSTOMER_ID"

Puedes usar el CustomerService.ListAccessibleCustomers método para recuperar la lista de cuentas a las que un usuario tiene acceso directo. Estas cuentas se pueden usar como valores válidos para el encabezado login-customer-id.

Java

private void runExample(GoogleAdsClient client) {
  // Optional: Change credentials to use a different refresh token, to retrieve customers
  //           available for a specific user.
  //
  // UserCredentials credentials =
  //     UserCredentials.newBuilder()
  //         .setClientId("INSERT_OAUTH_CLIENT_ID")
  //         .setClientSecret("INSERT_OAUTH_CLIENT_SECRET")
  //         .setRefreshToken("INSERT_REFRESH_TOKEN")
  //         .build();
  //
  // client = client.toBuilder().setCredentials(credentials).build();

  try (CustomerServiceClient customerService =
      client.getLatestVersion().createCustomerServiceClient()) {
    ListAccessibleCustomersResponse response =
        customerService.listAccessibleCustomers(
            ListAccessibleCustomersRequest.newBuilder().build());

    System.out.printf("Total results: %d%n", response.getResourceNamesCount());

    for (String customerResourceName : response.getResourceNamesList()) {
      System.out.printf("Customer resource name: %s%n", customerResourceName);
    }
  }
}

C#

public void Run(GoogleAdsClient client)
{
    // Get the CustomerService.
    CustomerServiceClient customerService = client.GetService(Services.V24.CustomerService);

    try
    {
        // Retrieve the list of customer resources.
        string[] customerResourceNames = customerService.ListAccessibleCustomers();

        // Display the result.
        foreach (string customerResourceName in customerResourceNames)
        {
            Console.WriteLine(
                $"Found customer with resource name = '{customerResourceName}'.");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

PHP

public static function runExample(GoogleAdsClient $googleAdsClient)
{
    $customerServiceClient = $googleAdsClient->getCustomerServiceClient();

    // Issues a request for listing all accessible customers.
    $accessibleCustomers =
        $customerServiceClient->listAccessibleCustomers(new ListAccessibleCustomersRequest());
    print 'Total results: ' . count($accessibleCustomers->getResourceNames()) . PHP_EOL;

    // Iterates over all accessible customers' resource names and prints them.
    foreach ($accessibleCustomers->getResourceNames() as $resourceName) {
        /** @var string $resourceName */
        printf("Customer resource name: '%s'%s", $resourceName, PHP_EOL);
    }
}

Python

def main(client: GoogleAdsClient) -> None:
    customer_service: CustomerServiceClient = client.get_service(
        "CustomerService"
    )

    accessible_customers: ListAccessibleCustomersResponse = (
        customer_service.list_accessible_customers()
    )
    result_total: int = len(accessible_customers.resource_names)
    print(f"Total results: {result_total}")

    resource_names: List[str] = accessible_customers.resource_names
    for resource_name in resource_names:  # resource_name is implicitly str
        print(f'Customer resource name: "{resource_name}"')

Ruby

def list_accessible_customers()
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  accessible_customers = client.service.customer.list_accessible_customers().resource_names

  accessible_customers.each do |resource_name|
    puts "Customer resource name: #{resource_name}"
  end
end

Perl

sub list_accessible_customers {
  my ($api_client) = @_;

  my $list_accessible_customers_response =
    $api_client->CustomerService()->list_accessible_customers();

  printf "Total results: %d.\n",
    scalar @{$list_accessible_customers_response->{resourceNames}};

  foreach
    my $resource_name (@{$list_accessible_customers_response->{resourceNames}})
  {
    printf "Customer resource name: '%s'.\n", $resource_name;
  }

  return 1;
}

curl

# Returns the resource names of customers directly accessible by the user
# authenticating the call.
#
# Variables:
#   API_VERSION,
#   DEVELOPER_TOKEN,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
curl -f --request GET \
"https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

¿Qué sucede si el método ListAccessibleCustomers no recupera mi ID de cliente?

Si el CustomerService.ListAccessibleCustomers método no recuperó un ID de cliente que esperabas que apareciera en los resultados, existen algunas explicaciones posibles.

  1. Tienes acceso al ID de cliente, pero el acceso se emite a través de una cuenta de administrador superior. Por ejemplo, si llamas al ListAccessibleCustomers método con las credenciales de usuario U1 en el ejemplo anterior, solo obtendrás M1 en los resultados, aunque U1 tenga acceso a más cuentas. Para confirmar esta posibilidad, recupera la jerarquía de cuentas de cada una de las cuentas que muestra el método ListAccessibleCustomers. Para ello, establece cada una de estas cuentas como login-customer-id, como se describe en la sección anterior. Si tienes acceso a la cuenta de destino, deberías poder recuperarla como parte de una de las jerarquías de cuentas.

  2. Estás usando credenciales de OAuth incorrectas. La situación más común es que uses las credenciales de un usuario diferente. Por ejemplo, podría deberse a que se mezclaron accidentalmente las credenciales de sandbox o de desarrollador con las credenciales de producción, o a que se leyeron incorrectamente las credenciales de un usuario diferente de la base de datos o la caché local. Una forma posible de solucionar este problema es usar la API de Google People para recuperar el nombre y la dirección de correo electrónico del usuario que accedió y verificar si coinciden con la dirección de correo electrónico que esperabas.

  3. No tienes acceso a la cuenta. Sigue las instrucciones para obtener acceso a la cuenta de cliente correcta.

Funciones de usuario

La API de Google Ads no tiene un modelo de acceso independiente ni usa alcances de OAuth 2.0 separados para limitar la funcionalidad. Por ejemplo, la API de Google Ads usa los mismos alcances para las operaciones de solo lectura y de lectura y escritura. En cambio, la API de Google Ads sigue las mismas funciones de usuario que admite Google Ads. Cuando se otorga una función de usuario a una cuenta a nivel del administrador, las cuentas de la jerarquía heredan la función. Si un usuario tiene funciones en conflicto para una cuenta determinada, el nivel correcto se resuelve con la cuenta login-customer-id especificada en la solicitud a la API.

En la siguiente tabla, se usa la jerarquía de cuentas del ejemplo anterior y se muestra el efecto de otorgar varias funciones de usuario a los usuarios.

Usuario Función de usuario otorgada login-customer-id Nivel de acceso efectivo
SA1 Acceso estándar en la cuenta M1 M1 Acceso estándar en M1, M2, A1, A2 y A3
U2 Acceso estándar en M2
Acceso de solo lectura en M3
 M2 Acceso estándar en M2, A1, A2 y A3
U2 Acceso estándar en M2
Acceso de solo lectura en M3
 M3 Acceso de solo lectura en M3, A1 y A4
Anterior
Introducción
Siguiente
Flujo de trabajo de la cuenta de servicio