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) oderCREATION_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_MANAGERoderMAX_DEPTH_EXCEEDED.AccessInvitationError: Wird zurückgegeben, wenn inCreateCustomerClientRequesteine optionaleemail_address(zusammen mitaccess_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_ALLOWEDoderEMAIL_DOMAIN_POLICY_VIOLATED). Konten, die nicht auf der Allowlist stehen, sollten Nutzer nach der Kontoerstellung mitCustomerUserAccessInvitationServiceeinladen.CurrencyCodeError.UNSUPPORTEDoderTimeZoneError.INVALID_TIME_ZONE: Wird zurückgegeben, wenn der angegebenecurrency_codeodertime_zoneimCustomer-Objekt ungültig oder nicht unterstützt wird.