Konto erstellen

Wenn Sie ein neues Kundenkonto erstellen möchten, senden Sie ein vorab ausgefülltes Customer Objekt mit der Methode CreateCustomerClient in CustomerService.

Im Gegensatz zur Erstellung von Standardentitäten (z. B. Kampagnen mit mutate-Aufrufen) müssen Sie in der Anfrage die Kunden-ID des Verwaltungskontos und nicht die ID des zu erstellenden Kunden angeben.

Anfrage- und Kundenfelder

Konfigurieren Sie beim Aufrufen von CustomerService.CreateCustomerClient CreateCustomerClientRequest und das darin eingebettete Customer-Objekt wie in der folgenden Tabelle gezeigt:

Feld oder Header Anforderung Änderbarkeit und Beschreibung
customer_id Erforderlich Die 10-stellige Kunden-ID (ohne Bindestriche) des direkten übergeordneten Verwaltungskontos , unter dem das neue Kundenkonto erstellt wird.
login-customer-id (Header) Bedingt In den Anfrageheadern erforderlich, wenn der authentifizierte Nutzer über ein übergeordnetes Verwaltungskonto in der Hierarchie auf das übergeordnete Verwaltungskonto (customer_id) zugreift.
customer_client.descriptive_name Erforderlich Änderbar:Anzeigename für das neue Konto (z. B. "Acct Created with CustomerService"). Kann später mit CustomerService.MutateCustomer aktualisiert werden.
customer_client.currency_code Erforderlich Nach der Erstellung unveränderlich: Dreistelliger ISO 4217-Code für die Abrechnungswährung (z. B. USD oder EUR). Informationen zu unterstützten Währungscodes.
customer_client.time_zone Erforderlich Nach der Erstellung unveränderlich: Zeitzonen-ID des Kontos (z. B. America/New_York). Informationen zu unterstützten Zeitzonen.
email_address und access_role Optional (nur Allowlist) Lädt einen Nutzer (ADMIN, STANDARD, READ_ONLY oder EMAIL_ONLY) während der Erstellung zum erstellten Konto ein. Für Konten, die nicht auf der Allowlist stehen, müssen Nutzer nach der Erstellung mit CustomerUserAccessInvitationService eingeladen werden.
validate_only Optional Wenn true, werden die Anfrageparameter und die Berechtigung des Verwaltungskontos validiert, ohne das Konto zu erstellen.

Codebeispiel

Das folgende Beispiel zeigt, wie Sie ein Kundenkonto unter einem vorhandenen Verwaltungskonto erstellen:

Java

private void runExample(GoogleAdsClient googleAdsClient, Long managerId) {
  // Formats the current date/time to use as a timestamp in the new customer description.
  String dateTime = ZonedDateTime.now().format(DateTimeFormatter.RFC_1123_DATE_TIME);

  // Initializes a Customer object to be created.
  Customer customer =
      Customer.newBuilder()
          .setDescriptiveName("Account created with CustomerService on '" + dateTime + "'")
          .setCurrencyCode("USD")
          .setTimeZone("America/New_York")
          // Optional: Sets additional attributes of the customer.
          .setTrackingUrlTemplate("{lpurl}?device={device}")
          .setFinalUrlSuffix("keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}")
          .build();

  // Sends the request to create the customer.
  try (CustomerServiceClient client =
      googleAdsClient.getLatestVersion().createCustomerServiceClient()) {
    CreateCustomerClientResponse response =
        client.createCustomerClient(managerId.toString(), customer);
    System.out.printf(
        "Created a customer with resource name '%s' under the manager account with"
            + " customer ID '%d'.%n",
        response.getResourceName(), managerId);
  }
}
      

C#

public void Run(GoogleAdsClient client, long managerCustomerId)
{
    // Get the CustomerService.
    CustomerServiceClient customerService = client.GetService(Services.V26.CustomerService);

    Customer customer = new Customer()
    {
        DescriptiveName = $"Account created with CustomerService on '{DateTime.Now}'",

        // For a list of valid currency codes and time zones see this documentation:
        // https://developers.google.com/google-ads/api/reference/data/codes-formats#codes_formats.
        CurrencyCode = "USD",
        TimeZone = "America/New_York",

        // The below values are optional. For more information about URL
        // options see: https://support.google.com/google-ads/answer/6305348.
        TrackingUrlTemplate = "{lpurl}?device={device}",
        FinalUrlSuffix = "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
    };

    try
    {
        // Create the account.
        CreateCustomerClientResponse response = customerService.CreateCustomerClient(
            managerCustomerId.ToString(), customer);

        // Display the result.
        Console.WriteLine($"Created a customer with resource name " +
            $"'{response.ResourceName}' under the manager account with customer " +
            $"ID '{managerCustomerId}'");
    }
    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, int $managerCustomerId)
{
    $customer = new Customer([
        'descriptive_name' => 'Account created with CustomerService on ' . date('Ymd h:i:s'),
        // For a list of valid currency codes and time zones see this documentation:
        // https://developers.google.com/google-ads/api/reference/data/codes-formats.
        'currency_code' => 'USD',
        'time_zone' => 'America/New_York',
        // The below values are optional. For more information about URL
        // options see: https://support.google.com/google-ads/answer/6305348.
        'tracking_url_template' => '{lpurl}?device={device}',
        'final_url_suffix' => 'keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}'
    ]);

    // Issues a mutate request to create an account
    $customerServiceClient = $googleAdsClient->getCustomerServiceClient();
    $response = $customerServiceClient->createCustomerClient(
        CreateCustomerClientRequest::build($managerCustomerId, $customer)
    );

    printf(
        'Created a customer with resource name "%s" under the manager account with '
        . 'customer ID %d.%s',
        $response->getResourceName(),
        $managerCustomerId,
        PHP_EOL
    );
}
      

Python

def main(client: GoogleAdsClient, manager_customer_id: str) -> None:
    """The main method that creates all necessary entities for the example.

    Args:
        client: an initialized GoogleAdsClient instance.
        manager_customer_id: a manager client customer ID.
    """
    customer_service: CustomerServiceClient = client.get_service(
        "CustomerService"
    )
    customer: Customer = client.get_type("Customer")
    now: str = datetime.today().strftime("%Y%m%d %H:%M:%S")
    customer.descriptive_name = f"Account created with CustomerService on {now}"
    # For a list of valid currency codes and time zones see this documentation:
    # https://developers.google.com/google-ads/api/reference/data/codes-formats
    customer.currency_code = "USD"
    customer.time_zone = "America/New_York"
    # The below values are optional. For more information about URL
    # options see: https://support.google.com/google-ads/answer/6305348
    customer.tracking_url_template = "{lpurl}?device={device}"
    customer.final_url_suffix = (
        "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
    )

    response: CreateCustomerClientResponse = (
        customer_service.create_customer_client(
            customer_id=manager_customer_id, customer_client=customer
        )
    )
    print(
        f'Customer created with resource name "{response.resource_name}" '
        f'under manager account with ID "{manager_customer_id}".'
    )
      

Ruby

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

  customer = client.resource.customer do |c|
    c.descriptive_name = "Account created with CustomerService on #{(Time.new.to_f * 1000).to_i}"

    # For a list of valid currency codes and time zones, see this documentation:
    # https://developers.google.com/google-ads/api/reference/data/codes-formats
    c.currency_code = "USD"
    c.time_zone = "America/New_York"

    # The below values are optional. For more information about URL options, see:
    # https://support.google.com/google-ads/answer/6305348
    c.tracking_url_template = "{lpurl}?device={device}"
    c.final_url_suffix = "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
  end

  response = client.service.customer.create_customer_client(
    customer_id: manager_customer_id,
    customer_client: customer
  )

  puts "Created a customer with resource name #{response.resource_name} under" +
      " the manager account with customer ID #{manager_customer_id}."
end
      

Perl

sub create_customer {
  my ($api_client, $manager_customer_id) = @_;

  # Initialize a customer to be created.
  my $customer = Google::Ads::GoogleAds::V26::Resources::Customer->new({
      descriptiveName => "Account created with CustomerService on #" . uniqid(),

      # For a list of valid currency codes and time zones, see this documentation:
      # https://developers.google.com/google-ads/api/reference/data/codes-formats
      currencyCode => "USD",
      timeZone     => "America/New_York",

      # The below values are optional. For more information about URL options, see:
      # https://support.google.com/google-ads/answer/6305348
      trackingUrlTemplate => "{lpurl}?device={device}",
      finalUrlSuffix      =>
        "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
  });

  # Create the customer client.
  my $create_customer_client_response =
    $api_client->CustomerService()->create_customer_client({
      customerId     => $manager_customer_id,
      customerClient => $customer
    });

  printf
    "Created a customer with resource name '%s' under the manager account " .
    "with customer ID %d.\n", $create_customer_client_response->{resourceName},
    $manager_customer_id;

  return 1;
}
      

curl

# Creates a customer client.
#
# Variables:
#   API_VERSION,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "customerClient": {
    "descriptiveName": "Account created with CustomerService #${RANDOM}",
    "currencyCode": "USD",
    "timeZone": "America/New_York"
  }
}
EOF
      

Antwort und nächste Schritte

Bei Erfolg gibt CreateCustomerClient eine CreateCustomerClientResponse mit dem resource_name (customers/{new_customer_id}) des neu erstellten Kontos zurück. Wenn email_address und access_role von einem Verwaltungskonto auf der Allowlist angegeben wurden, wird auch ein invitation_link zurückgegeben. Sie können diesen Ressourcennamen oder die Kundennummer dann verwenden, um das Konto in Ihrer Hierarchie zu bestätigen, Nutzerzugriff zu gewähren, die Abrechnung zu konfigurieren oder Kampagnen zu erstellen.

Erstelltes Konto in der Verwaltungskontohierarchie bestätigen

Fragen Sie die customer_client Ressource für das Verwaltungskonto (customer_id) mit GoogleAdsService.SearchStream ab, um das neu erstellte Unterkonto zu prüfen:

SELECT
  customer_client.id,
  customer_client.resource_name,
  customer_client.client_customer,
  customer_client.descriptive_name,
  customer_client.currency_code,
  customer_client.time_zone,
  customer_client.manager,
  customer_client.level,
  customer_client.status
FROM customer_client
WHERE customer_client.level = 1
  AND customer_client.id = {new_customer_id}

Nutzer zum neuen Konto einladen

Wenn Ihr Verwaltungskonto nicht auf der Allowlist steht, um email_address und access_role direkt in CreateCustomerClientRequest festzulegen, senden Sie eine Einladung für den Zugriff auf die neu erstellte new_customer_id mit MutateCustomerUserAccessInvitation in CustomerUserAccessInvitationService. Wenn Sie sich über das übergeordnete Verwaltungskonto authentifizieren, fügen Sie login-customer-id: {manager_customer_id} in die HTTP-Anfrageheader ein:

POST https://googleads.googleapis.com/v26/customers/{new_customer_id}/customerUserAccessInvitations:mutate
{
  "operation": {
    "create": {
      "emailAddress": "user@example.com",
      "accessRole": "ADMIN"
    }
  }
}

Fehlerbehandlung

Aufrufe von CreateCustomerClient können die folgenden Fehler zurückgeben:

  • CustomerError: Gibt Einschränkungen bei der Kontoerstellung auf Kontoebene an, z. B. CREATION_DENIED_INELIGIBLE_MCC (das Verwaltungskonto ist nicht berechtigt, neue Konten zu erstellen) oder CREATION_DENIED_FOR_POLICY_VIOLATION (die Kundenerstellung wurde aufgrund eines Richtlinienverstoßes abgelehnt).
  • ManagerLinkError: Gibt Einschränkungen in Bezug auf die Hierarchie oder das Kontolimit an, z. B. TOO_MANY_ACCOUNTS, TOO_MANY_ACCOUNTS_AT_MANAGER oder MAX_DEPTH_EXCEEDED.
  • AccessInvitationError: Wird zurückgegeben, wenn in CreateCustomerClientRequest eine optionale email_address (zusammen mit access_role, nur für Konten auf der Allowlist verfügbar) angegeben wird, um einen Nutzer zum neuen Konto einzuladen, und die Einladung fehlschlägt (z. B. INVALID_EMAIL_ADDRESS, GOOGLE_CONSUMER_ACCOUNT_NOT_ALLOWED oder EMAIL_DOMAIN_POLICY_VIOLATED). Konten, die nicht auf der Allowlist stehen, sollten Nutzer nach der Kontoerstellung mit CustomerUserAccessInvitationService einladen.
  • CurrencyCodeError.UNSUPPORTED oder TimeZoneError.INVALID_TIME_ZONE: Wird zurückgegeben, wenn der angegebene currency_code oder time_zone im Customer-Objekt ungültig oder nicht unterstützt wird.