Google Ads-Zugriffsmodell

Es gibt zwei Arten von Google Ads-Konten: Google Ads-Verwaltungskonten und Google Ads-Werbekonten. Eine ausführliche Erläuterung dazu, wie diese und andere Begriffe (z. B. Kundenkonto und Kunde) zusammenhängen, finden Sie unter Kontotypen.

Über Verwaltungskonten können andere Google Ads-Verwaltungskonten oder Google Ads-Werbetreibendenkonten verwaltet werden. Sie können ein Werbetreibendenkonto mit einem Verwaltungskonto verknüpfen und das Werbetreibendenkonto dann über das Verwaltungskonto verwalten. Die gesamte verknüpfte Struktur ist ein gerichteter azyklischer Graph mit Werbetreibendenkonten auf der Blattebene.

Sie können einzelnen Nutzern oder Dienstkonten Zugriff auf Google Ads-Konten gewähren. Es gibt zwei Möglichkeiten, Nutzern Zugriff auf ein Werbetreibendenkonto zu gewähren:

• Gewähren Sie dem Nutzer direkten Zugriff auf das Werbetreibendenkonto, indem Sie ihn zu diesem Konto einladen.
• Gewähren Sie dem Nutzer indirekten Zugriff auf das Werbetreibendenkonto, indem Sie ihn zu einem Verwaltungskonto einladen, das mit diesem Konto verknüpft ist. Der Nutzer erhält Zugriff auf das Werbetreibendenkonto, da das Verwaltungskonto Zugriff auf alle damit verknüpften Konten hat.

Sie können auch Nutzerrollen zuweisen, wenn Sie einen Nutzer einladen, ein Konto zu verwalten.

Sehen Sie sich die folgende Kontohierarchie an. Angenommen, alle Nutzer haben Standardzugriff.

In der folgenden Tabelle wird diese Kontostruktur zusammengefasst.

Nutzer	Hat direkten Zugriff auf	Hat indirekten Zugriff auf
U1, SA1	M1	M2, A1, A2, A3
U2	M2, M3	A1, A2, A3, A4
U3	A4

Kundennummer für die Anmeldung

Ein Nutzer kann Zugriff auf mehrere Kontohierarchien haben. Wenn Sie in solchen Fällen einen API-Aufruf ausführen, müssen Sie das Stammkonto angeben, das verwendet werden soll, um die Autorisierungs- und Kontozugriffsebenen korrekt zu bestimmen. Fügen Sie dazu den Header login-customer-id in Ihre API-Anfrage ein.

In der folgenden Tabelle wird die Kontohierarchie aus dem vorherigen Beispiel verwendet, um zu zeigen, welche Kundennummern für die Anmeldung Sie verwenden können und welche Konten Sie aufrufen können.

Nutzer	Kundennummer für die Anmeldung	Konten, für die API-Aufrufe ausgeführt werden sollen
U1, SA1	M1	M1, M2, A1, A2, A3
U2	M2	M2, A1, A2, A3
U2	M3	M3, A1, A4
U3	A4	A4

Sie können den Header login-customer-id weglassen, wenn der Nutzer direkten Zugriff auf das Google Ads-Konto hat, an das Sie Aufrufe senden. Sie müssen beispielsweise den Header login-customer-id nicht angeben, wenn Sie U3-Anmeldedaten verwenden, um einen Aufruf an A4 zu senden, da die Google Ads-Server die Zugriffsebene anhand der Kundennummer (A4) korrekt bestimmen können.

Wenn Sie eine Google Ads API-Clientbibliothek verwenden, geben Sie den Header login-customer-id mit den folgenden Einstellungen an.

Java

Fügen Sie der Datei ads.properties die folgende Einstellung hinzu.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

.NET

Fügen Sie die folgende Einstellung hinzu, wenn Sie das GoogleAdsConfig-Objekt initialisieren, und verwenden Sie es, um ein GoogleAdsClient-Objekt zu erstellen.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // ...
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

Python

Fügen Sie der Datei google-ads.yaml die folgende Einstellung hinzu.

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

PHP

Fügen Sie der Datei google_ads_php.ini die folgende Einstellung hinzu.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Ruby

Fügen Sie der Datei google_ads_config.rb die folgende Einstellung hinzu.

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

Erstellen Sie eine GoogleAdsClient-Instanz, indem Sie den Pfad zu dem Speicherort dieser Datei übergeben.

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

Perl

Fügen Sie der Datei googleads.properties die folgende Einstellung hinzu.

loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

curl

Geben Sie beim Ausführen des Befehls curl das folgende Befehlszeilenargument an.

-H "login-customer-id: INSERT_LOGIN_CUSTOMER_ID_HERE"

Mit der Methode CustomerService.ListAccessibleCustomers können Sie die Liste der Konten abrufen, auf die ein Nutzer direkten Zugriff hat. Diese Konten können als gültige Werte für den Header login-customer-id verwendet werden.

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);
    }
  }
}
ListAccessibleCustomers.java
      

C#

public void Run(GoogleAdsClient client)
{
    // Get the CustomerService.
    CustomerServiceClient customerService = client.GetService(Services.V26.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;
    }
}
ListAccessibleCustomers.cs
      

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);
    }
}
ListAccessibleCustomers.php
      

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}"')
list_accessible_customers.py
      

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

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

curl

# Returns the resource names of customers directly accessible by the user
# authenticating the call.
#
# Variables:
#   API_VERSION,
#   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 "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
list_accessible_customers.sh
      

Was kann ich tun, wenn die Methode ListAccessibleCustomers meine Kundennummer nicht abruft?

Wenn die Methode CustomerService.ListAccessibleCustomers keine Kundennummer abgerufen hat, die Sie in den Ergebnissen erwartet haben, kann das verschiedene Gründe haben.

1. Sie haben Zugriff auf die Kundennummer, aber der Zugriff wird über ein übergeordnetes Verwaltungskonto gewährt. Wenn Sie beispielsweise die Methode ListAccessibleCustomers mit den Anmeldedaten des Nutzers U1 im vorherigen Beispiel aufrufen, gibt die Methode nur M1 in den Ergebnissen zurück, obwohl U1 Zugriff auf mehr Konten hat. Um diese Möglichkeit zu bestätigen, rufen Sie die Kontohierarchie ab. Führen Sie dazu für jedes der von der Methode ListAccessibleCustomers zurückgegebenen Konten search- oder searchStream-Abfragen für die Ressource customer_client aus. Legen Sie dazu jedes dieser Konten als login-customer-id fest, wie im vorherigen Abschnitt beschrieben. Wenn Sie Zugriff auf das Zielkonto haben, können Sie es als Teil einer der Kontohierarchien abrufen.

2. Sie verwenden falsche OAuth-Anmeldedaten. Das häufigste Szenario ist, dass Sie die Anmeldedaten eines anderen Nutzers verwenden. Dies kann beispielsweise daran liegen, dass Sandbox- oder Entwickleranmeldedaten versehentlich mit Produktionsanmeldedaten verwechselt wurden oder die Anmeldedaten eines anderen Nutzers fälschlicherweise aus der Datenbank oder dem lokalen Cache gelesen wurden. Eine Möglichkeit, dieses Problem zu beheben, besteht darin, mit der Google People API den Namen und die E-Mail-Adresse des angemeldeten Nutzers abzurufen und zu prüfen, ob sie mit der erwarteten E-Mail-Adresse übereinstimmen.

3. Sie haben keinen Zugriff auf das Konto. Folgen Sie der Anleitung für den Kontozugriff, um Zugriff auf das richtige Kundenkonto zu erhalten.

Nutzerrollen

Die Google Ads API hat kein eigenes Zugriffsmodell und verwendet keine separaten OAuth 2.0-Bereiche, um die Funktionalität einzuschränken. Die Google Ads API verwendet beispielsweise dieselben Bereiche für Lese- und Schreibvorgänge. Stattdessen werden in der Google Ads API dieselben Nutzerrollen verwendet, die auch in Google Ads unterstützt werden. Wenn einem Konto auf Verwaltungsebene eine Nutzerrolle zugewiesen wird, wird die Rolle von den Konten in der Hierarchie übernommen. Wenn ein Nutzer widersprüchliche Rollen für ein bestimmtes Konto hat, wird die richtige Ebene durch das in der API-Anfrage angegebene login-customer-id-Konto aufgelöst.

In der folgenden Tabelle wird die Kontohierarchie aus dem vorherigen Beispiel verwendet und die Auswirkung der Zuweisung verschiedener Nutzerrollen zu Nutzern gezeigt.

Nutzer	Nutzerrolle gewährt	login-customer-id	Tatsächliche Zugriffsebene
SA1	Standardzugriff auf Konto M1	M1	Standardzugriff auf M1, M2, A1, A2, A3
U2	Standardzugriff auf M2 Lesezugriff auf M3	M2	Standardzugriff auf M2, A1, A2, A3
U2	Standardzugriff auf M2 Lesezugriff auf M3	M3	Lesezugriff auf M3, A1, A4