Konto erstellen

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

Im Gegensatz zur Standarderstellung von Entitäten (z. B. Erstellen von Kampagnen mit mutate-Aufrufen) müssen Sie in der Anfrage die Kundennummer des Verwaltungskontos angeben, nicht die ID des Kunden, der erstellt wird.

Anfrage- und Kundenfelder

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

Feld oder Header Anforderung Veränderlichkeit und Beschreibung
customer_id Erforderlich Die 10-stellige Kundennummer (ohne Bindestriche) des direkt übergeordneten Verwaltungskontos, unter dem das neue Kundenkonto erstellt wird.
login-customer-id (Header) Bedingt Erforderlich in den Anfrageheadern, wenn der authentifizierte Nutzer über ein übergeordnetes Verwaltungskonto, das in der Hierarchie höher liegt, auf das übergeordnete Verwaltungskonto (customer_id) zugreift.
customer_client.descriptive_name Erforderlich Veränderlich: 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-Abrechnungswährungscode (z. B. USD oder EUR). Weitere Informationen finden Sie unter Unterstützte Währungscodes.
customer_client.time_zone Erforderlich Nach der Erstellung nicht mehr veränderbar: Zeitzonen-ID des Kontos (z. B. America/New_York). Weitere Informationen finden Sie unter Unterstützte Zeitzonen.
email_address und access_role Optional (nur Zulassungsliste) Lädt einen Nutzer (ADMIN, STANDARD, READ_ONLY oder EMAIL_ONLY) während der Erstellung in das erstellte Konto ein. In Konten, die nicht auf der Zulassungsliste stehen, müssen Nutzer nach der Erstellung über CustomerUserAccessInvitationService eingeladen werden.
validate_only Optional Wenn true, werden die Anfrageparameter und die Berechtigung des Verwalters validiert, ohne dass das Konto erstellt wird.

Codebeispiel

Im folgenden Beispiel wird gezeigt, 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 ein CreateCustomerClientResponse mit der resource_name (customers/{new_customer_id}) des neu erstellten Kontos zurück (plus ein invitation_link, wenn email_address und access_role von einem Verwaltungskonto auf der Zulassungsliste enthalten waren). Anschließend können Sie diesen Ressourcennamen oder diese Kundennummer 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 Verwaltungshierarchie bestätigen

Fragen Sie die Ressource customer_client 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 in das neue Konto einladen

Wenn Ihr Verwaltungskonto nicht auf der Zulassungsliste für das direkte Festlegen von email_address und access_role für CreateCustomerClientRequest steht, senden Sie eine Zugriffseinladung an das neu erstellte new_customer_id. Verwenden Sie dazu MutateCustomerUserAccessInvitation für 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 für die Erstellung auf Kontoebene an, z. B. CREATION_DENIED_INELIGIBLE_MCC (mit dem Verwaltungskonto können keine neuen Konten erstellt werden) oder CREATION_DENIED_FOR_POLICY_VIOLATION (die Erstellung von Kundenkonten wird aufgrund eines Richtlinienverstoßes abgelehnt).
  • ManagerLinkError: Gibt Einschränkungen der Hierarchie oder des Kontolimits an, z. B. TOO_MANY_ACCOUNTS, TOO_MANY_ACCOUNTS_AT_MANAGER oder MAX_DEPTH_EXCEEDED.
  • AccessInvitationError: Wird zurückgegeben, wenn ein optionaler email_address (zusammen mit access_role, nur für Konten auf der Zulassungsliste verfügbar) in CreateCustomerClientRequest angegeben wird, um einen Nutzer in das neue 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 Zulassungsliste stehen, sollten Nutzer nach der Kontoerstellung mit CustomerUserAccessInvitationService einladen.
  • CurrencyCodeError.UNSUPPORTED oder TimeZoneError.INVALID_TIME_ZONE: Wird zurückgegeben, wenn die angegebene currency_code oder time_zone im Customer-Objekt ungültig oder nicht unterstützt ist.
Zurück
Übersicht
Weiter
Mit Verwaltungskonten verknüpfen