Платежная настройка – это связь на уровне аккаунта между аккаунтом Google Реклама и платежным аккаунтом (также известная как настройка счета -фактуры ), которая эффективно определяет, кому выставляются счета за расходы, понесенные в соответствии с бюджетом аккаунта, заданным в настройках платежного аккаунта. Каждый аккаунт Payments соответствует одному счету.
О платежных аккаунтах
Каждый BillingSetup идентифицирует учетную запись Payments, для которой выставляются счета за расходы, понесенные в соответствии с бюджетами ее учетной записи. Этот платежный аккаунт связан с платежным профилем , который в конечном итоге отвечает за оплату.
Настройки выставления счетов содержат как поле payments_account , так и группу полей payments_account_info , которые определяют, используется ли аккаунт Payments, включая следующие:
-
payments_account_info.payments_account_id: 16-значный идентификатор, используемый для идентификации учетной записи Payments, связанной с настройкой выставления счетов. - Payments_account_info.payments_account_name : имя
payments_account_info.payments_account_nameаккаунта, связанного с настройкой выставления счетов. Это имя печатается на ежемесячных счетах-фактурах. -
payments_account_info.payments_profile_id: 12-значный идентификатор, используемый для идентификации платежного профиля, связанного с настройкой выставления счетов.
Если платежный аккаунт подходит для объединенного выставления счетов , несколько аккаунтов Google Рекламы можно сгруппировать в одном счете, настроив их платежные настройки для использования одного и того же базового платежного аккаунта.
Создание новых платежных настроек
Вы можете связать новые настройки выставления счетов с существующими учетными записями Payments или созданными в то же время.
Использование существующего платежного аккаунта
Чтобы связать существующую учетную запись Payments, задайте для payments_account идентификатор ресурса действительной учетной записи Payments. Однако не изменяйте payments_account_info .
Вы можете перечислить доступные платежные счета с помощью метода PaymentsAccountService.ListPaymentsAccounts . Возвращаемые PaymentsAccounts зависят от управляющей учетной записи, которую вы используете для аутентификации.
Для каждого PaymentsAccount идентификатор платежного менеджера находится в поле paying_manager_customer .
Использование нового платежного аккаунта
Чтобы установить связь с новой учетной записью Payments, задайте следующие поля в payments_account_info ( не устанавливайте payments_account ):
В приведенном ниже примере показано, как создать новую платежную настройку на основе существующего идентификатора платежного профиля. Как указано выше, это также создаст новую учетную запись Payments с именем My New Payments Account .
BillingSetup bsetup = BillingSetup.newBuilder()
.setPaymentsAccountInfo(PaymentsAccountInfo.newBuilder()
.setPaymentsAccountName("My New Payments Account")
.setPaymentsProfileId("1234-5678-9012")
.build())
.setStartTimeType(TimeType.NOW)
.build();
BillingSetupOperation op = BillingSetupOperation.newBuilder().setCreate(bsetup).build();
try (BillingSetupServiceClient billingSetupServiceClient = googleAdsClient
.getBillingSetupServiceClient()) {
MutateBillingSetupResponse response =
billingSetupServiceClient.mutateBillingSetup(Long.toString(customerId), op);
}
Если это первая настройка выставления счетов, добавляемая в аккаунт Google Рекламы, это фактически зарегистрирует клиента для выставления счетов с использованием указанного платежного профиля.
Статус настройки платежных данных
Новые экземпляры BillingSetup подлежат утверждению, прежде чем они вступят в силу. До тех пор их status находится в состоянии PENDING .
BillingSetup может находиться в одном из следующих status :
| Статус настройки оплаты | Описание |
|---|---|
PENDING | В ожидании утверждения. |
APPROVED_HELD | Утвержден, но соответствующий первый бюджет еще не принят. Это может произойти только для настроек выставления счетов, настроенных на ежемесячное выставление счетов. |
APPROVED | Установка была одобрена. |
CANCELLED | Установка была отменена пользователем до утверждения. |
Получение платежных настроек учетной записи
Как и большинство других сущностей в Google Ads API, BillingSetup извлекается путем запроса GoogleAdsService.SearchStream с использованием запроса языка запросов Google Ads, который указывает, какие поля возвращать.
Ява
private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
// Defines a GAQL query to retrieve all billing setup information.
String searchQuery =
"SELECT billing_setup.id, "
+ " billing_setup.status, "
+ " billing_setup.payments_account, "
+ " billing_setup.payments_account_info.payments_account_id, "
+ " billing_setup.payments_account_info.payments_account_name, "
+ " billing_setup.payments_account_info.payments_profile_id, "
+ " billing_setup.payments_account_info.payments_profile_name, "
+ " billing_setup.payments_account_info.secondary_payments_profile_id "
+ "FROM billing_setup";
// Creates a request that will retrieve all billing setups using pages of the specified
// page size.
SearchGoogleAdsRequest request =
SearchGoogleAdsRequest.newBuilder()
.setCustomerId(String.valueOf(customerId))
.setPageSize(PAGE_SIZE)
.setQuery(searchQuery)
.build();
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
// Issues the search request.
SearchPagedResponse response = googleAdsServiceClient.search(request);
// Iterates over all rows in all pages and prints the requested field values for the billing
// setup in each row.
for (GoogleAdsRow googleAdsRow : response.iterateAll()) {
BillingSetup billingSetup = googleAdsRow.getBillingSetup();
System.out.printf(
"Billing setup with ID '%d', "
+ "status '%s', "
+ "payments_account '%s', "
+ "payments_account_id '%s', "
+ "payments_account_name '%s', "
+ "payments_profile_id '%s', "
+ "payments_profile_name '%s', "
+ "secondary_payments_profile_id '%s'.%n",
billingSetup.getId(),
billingSetup.getStatus(),
billingSetup.getPaymentsAccount(),
billingSetup.getPaymentsAccountInfo().getPaymentsAccountId(),
billingSetup.getPaymentsAccountInfo().getPaymentsAccountName(),
billingSetup.getPaymentsAccountInfo().getPaymentsProfileId(),
billingSetup.getPaymentsAccountInfo().getPaymentsProfileName(),
billingSetup.getPaymentsAccountInfo().getSecondaryPaymentsProfileId());
}
}
}
С#
public void Run(GoogleAdsClient client, long customerId)
{
// Get the GoogleAdsServiceClient.
GoogleAdsServiceClient googleAdsService = client.GetService(
Services.V12.GoogleAdsService);
// Define a GAQL query to retrieve all billing setup information.
string searchQuery = @"
SELECT
billing_setup.id,
billing_setup.status,
billing_setup.payments_account,
billing_setup.payments_account_info.payments_account_id,
billing_setup.payments_account_info.payments_account_name,
billing_setup.payments_account_info.payments_profile_id,
billing_setup.payments_account_info.payments_profile_name,
billing_setup.payments_account_info.secondary_payments_profile_id
FROM billing_setup";
// Creates a request that will retrieve all billing setups using pages of the specified
// page size.
SearchGoogleAdsRequest request = new SearchGoogleAdsRequest()
{
PageSize = PAGE_SIZE,
Query = searchQuery,
CustomerId = customerId.ToString()
};
try
{
PagedEnumerable<SearchGoogleAdsResponse, GoogleAdsRow> searchPagedResponse =
googleAdsService.Search(request);
foreach (GoogleAdsRow googleAdsRow in searchPagedResponse)
{
BillingSetup billingSetup = googleAdsRow.BillingSetup;
Console.WriteLine($"Billing setup with ID '{billingSetup.Id}'has status " +
$"'{billingSetup.Status}'.");
// A missing billing setup will have no payments account information.
if (billingSetup.HasPaymentsAccount)
{
Console.WriteLine(
$"\tPayments account: {billingSetup.PaymentsAccount}\n" +
"\tPayments account Id: " +
$"{billingSetup.PaymentsAccountInfo.PaymentsAccountId}\n" +
"\tPayments profile id: " +
$"{billingSetup.PaymentsAccountInfo.PaymentsProfileId}\n");
// A pending billing setup will not have values for certain fields.
if (billingSetup.Status != BillingSetupStatus.Pending)
{
Console.WriteLine(
"\tPayments account name: " +
$"{billingSetup.PaymentsAccountInfo.PaymentsAccountName}\n" +
"\tPayments profile name: " +
$"{billingSetup.PaymentsAccountInfo.PaymentsProfileName}\n" +
"\tSecondary payments profile id: " +
$"{billingSetup.PaymentsAccountInfo.SecondaryPaymentsProfileId}");
}
}
else
{
Console.WriteLine("Payments account details missing or incomplete.");
}
}
}
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 $customerId)
{
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that retrieves the billing setups.
$query = 'SELECT billing_setup.id, '
. ' billing_setup.status, '
. ' billing_setup.payments_account_info.payments_account_id, '
. ' billing_setup.payments_account_info.payments_account_name, '
. ' billing_setup.payments_account_info.payments_profile_id, '
. ' billing_setup.payments_account_info.payments_profile_name, '
. ' billing_setup.payments_account_info.secondary_payments_profile_id '
. 'FROM billing_setup';
// Issues a search request by specifying page size.
$response =
$googleAdsServiceClient->search($customerId, $query, ['pageSize' => self::PAGE_SIZE]);
// Iterates over all rows in all pages and prints the requested field values for
// the billing setup in each row.
foreach ($response->iterateAllElements() as $googleAdsRow) {
/** @var GoogleAdsRow $googleAdsRow */
$paymentAccountInfo = $googleAdsRow->getBillingSetup()->getPaymentsAccountInfo();
if (is_null($paymentAccountInfo)) {
printf(
'Found the billing setup with ID %1$d, %3$s'
. ' status \'%2$d\' with no payment account info. %3$s',
$googleAdsRow->getBillingSetup()->getId(),
$googleAdsRow->getBillingSetup()->getStatus(),
PHP_EOL
);
continue;
}
printf(
'Found the billing setup with ID %1$d, %8$s'
. ' status \'%2$s\', %8$s'
. ' payments account ID \'%3$s\', %8$s'
. ' payments account name \'%4$s\', %8$s'
. ' payments profile ID \'%5$s\', %8$s'
. ' payments profile name \'%6$s\', %8$s'
. ' secondary payments profile ID \'%7$s\'.%8$s',
$googleAdsRow->getBillingSetup()->getId(),
BillingSetupStatus::name($googleAdsRow->getBillingSetup()->getStatus()),
$paymentAccountInfo->getPaymentsAccountId(),
$paymentAccountInfo->getPaymentsAccountName(),
$paymentAccountInfo->getPaymentsProfileId(),
$paymentAccountInfo->getPaymentsProfileName(),
$paymentAccountInfo->getSecondaryPaymentsProfileId()
? $paymentAccountInfo->getSecondaryPaymentsProfileId()
: 'None',
PHP_EOL
);
}
}
питон
def main(client, customer_id):
ga_service = client.get_service("GoogleAdsService")
query = """
SELECT
billing_setup.id,
billing_setup.status,
billing_setup.payments_account,
billing_setup.payments_account_info.payments_account_id,
billing_setup.payments_account_info.payments_account_name,
billing_setup.payments_account_info.payments_profile_id,
billing_setup.payments_account_info.payments_profile_name,
billing_setup.payments_account_info.secondary_payments_profile_id
FROM billing_setup"""
stream = ga_service.search_stream(customer_id=customer_id, query=query)
print("Found the following billing setup results:")
for batch in stream:
for row in batch.results:
billing_setup = row.billing_setup
pai = billing_setup.payments_account_info
if pai.secondary_payments_profile_id:
secondary_payments_profile_id = (
pai.secondary_payments_profile_id
)
else:
secondary_payments_profile_id = "None"
print(
f"Billing setup with ID {billing_setup.id}, "
f'status "{billing_setup.status.name}", '
f'payments_account "{billing_setup.payments_account}" '
f"payments_account_id {pai.payments_account_id}, "
f'payments_account_name "{pai.payments_account_name}", '
f"payments_profile_id {pai.payments_profile_id}, "
f'payments_profile_name "{pai.payments_profile_name}", '
"secondary_payments_profile_id "
f"{secondary_payments_profile_id}."
)
Рубин
def get_billing_setup(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
ga_service = client.service.google_ads
search_query = <<~QUERY
SELECT billing_setup.id,
billing_setup.status,
billing_setup.payments_account,
billing_setup.payments_account_info.payments_account_id,
billing_setup.payments_account_info.payments_account_name,
billing_setup.payments_account_info.payments_profile_id,
billing_setup.payments_account_info.payments_profile_name,
billing_setup.payments_account_info.secondary_payments_profile_id
FROM billing_setup
QUERY
response = ga_service.search(
customer_id: customer_id,
query: search_query,
page_size: PAGE_SIZE,
)
response.each do |row|
billing_setup = row.billing_setup
payments_account_info = billing_setup.payments_account_info
puts sprintf('Billing setup with ID "%s", status "%s",'\
' payments_account "%s", payments_account_id "%s",'\
' payments_account_name "%s", payments_profile_id "%s",'\
' payments_profile_name "%s", secondary_payments_profile_id "%s"',
billing_setup.id,
billing_setup.status,
billing_setup.payments_account,
payments_account_info ? payments_account_info.payments_account_id : "N/A",
payments_account_info ? payments_account_info.payments_account_name : "N/A",
payments_account_info ? payments_account_info.payments_profile_id : "N/A",
payments_account_info ? payments_account_info.payments_profile_name : "N/A",
payments_account_info ? payments_account_info.secondary_payments_profile_id : "N/A"
)
end
end
Перл
sub get_billing_setup {
my ($api_client, $customer_id) = @_;
# Create a query that retrieves the billing setups.
my $search_query =
"SELECT billing_setup.id, billing_setup.status, " .
"billing_setup.payments_account, " .
"billing_setup.payments_account_info.payments_account_id, " .
"billing_setup.payments_account_info.payments_account_name, " .
"billing_setup.payments_account_info.payments_profile_id, " .
"billing_setup.payments_account_info.payments_profile_name, " .
"billing_setup.payments_account_info.secondary_payments_profile_id " .
"FROM billing_setup";
# Create a search Google Ads request that will retrieve the billing setups
# using pages of the specified page size.
my $search_request =
Google::Ads::GoogleAds::V12::Services::GoogleAdsService::SearchGoogleAdsRequest
->new({
customerId => $customer_id,
query => $search_query,
pageSize => PAGE_SIZE
});
# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();
my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({
service => $google_ads_service,
request => $search_request
});
# Iterate over all rows in all pages and print the requested field values for
# the billing setup in each row.
while ($iterator->has_next) {
my $google_ads_row = $iterator->next;
my $billing_setup = $google_ads_row->{billingSetup};
my $payment_account_info = $billing_setup->{paymentsAccountInfo};
if (!$payment_account_info) {
printf "Found the billing setup with ID %d, status '%s' " .
"with no payment account info.\n", $billing_setup->{id},
$billing_setup->{status};
next;
}
printf "Found the billing setup with ID %d, status '%s', " .
"payments account '%s', " .
"payments account ID '%s', payments account name '%s', " .
"payments profile ID '%s', payments profile name '%s', " .
"secondary payments profile ID '%s'.\n",
$billing_setup->{id}, $billing_setup->{status},
$billing_setup->{paymentsAccount},
$payment_account_info->{paymentsAccountId},
$payment_account_info->{paymentsAccountName},
$payment_account_info->{paymentsProfileId},
$payment_account_info->{paymentsProfileName},
$payment_account_info->{secondaryPaymentsProfileId}
? $payment_account_info->{secondaryPaymentsProfileId}
: "None";
}
return 1;
}
Получив ссылку на BillingSetup , вы можете использовать ее для создания AccountBudgetProposal , как описано в разделе Бюджет учетной записи .
Отмена незавершенной платежной настройки
BillingSetup , который еще не вступил в силу, можно отменить с помощью операции удаления. Настройки платежных данных можно отменить только в том случае, если они имеют status PENDING или если они APPROVED для запуска в будущем.
Ява
private void runExample(GoogleAdsClient googleAdsClient, long customerId, long billingSetupId) {
// Formats the customerId and billingSetupId into a resource name.
String billingSetupResourceName = ResourceNames.billingSetup(customerId, billingSetupId);
// Constructs an operation that will remove the billing setup.
BillingSetupOperation operation =
BillingSetupOperation.newBuilder().setRemove(billingSetupResourceName).build();
try (BillingSetupServiceClient billingSetupServiceClient =
googleAdsClient.getLatestVersion().createBillingSetupServiceClient()) {
// Sends the operation in a mutate request.
MutateBillingSetupResponse response =
billingSetupServiceClient.mutateBillingSetup(String.valueOf(customerId), operation);
System.out.printf(
"Removed billing setup with resource name '%s'.%n",
response.getResult().getResourceName());
}
}
С#
public void Run(GoogleAdsClient client, long customerId, long billingSetupId)
{
// Get the BillingSetupServiceClient.
BillingSetupServiceClient billingSetupService = client.GetService(
Services.V12.BillingSetupService);
// Create the billing setup resource.
String billingSetupResource = ResourceNames.BillingSetup(customerId, billingSetupId);
// Construct an operation that will remove the billing setup.
BillingSetupOperation operation = new BillingSetupOperation()
{
Remove = billingSetupResource
};
try
{
// Send the operation in a mutate request.
MutateBillingSetupResponse response =
billingSetupService.MutateBillingSetup(customerId.ToString(), operation);
Console.WriteLine("Removed billing setup with resource name '{0}'.",
response.Result.ResourceName);
}
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 $customerId,
int $billingSetupId
) {
// Creates the resource name of a billing setup to remove.
$billingSetupResourceName = ResourceNames::forBillingSetup($customerId, $billingSetupId);
// Creates a billing setup operation.
$billingSetupOperation = new BillingSetupOperation();
$billingSetupOperation->setRemove($billingSetupResourceName);
// Issues a mutate request to remove the billing setup.
$billingSetupServiceClient = $googleAdsClient->getBillingSetupServiceClient();
$response =
$billingSetupServiceClient->mutateBillingSetup($customerId, $billingSetupOperation);
/** @var BillingSetup $removedBillingSetup */
$removedBillingSetup = $response->getResult();
printf(
"Removed billing setup with resource name '%s'%s",
$removedBillingSetup->getResourceName(),
PHP_EOL
);
}
питон
def main(client, customer_id, billing_setup_id):
billing_setup_service = client.get_service("BillingSetupService")
# Create billing setup operation.
billing_setup_operation = client.get_type("BillingSetupOperation")
billing_setup_operation.remove = billing_setup_service.billing_setup_path(
customer_id, billing_setup_id
)
# Remove the billing setup.
billing_setup_response = billing_setup_service.mutate_billing_setup(
customer_id=customer_id, operation=billing_setup_operation
)
print(
"Removed billing setup "
f'"{billing_setup_response.results[0].resource_name}"'
)
Рубин
def remove_billing_setup(customer_id, billing_setup_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
billing_setup_service = client.service.billing_setup
resource = client.path.billing_setup(customer_id, billing_setup_id)
operation = client.operation.remove_resource.billing_setup(resource)
response = billing_setup_service.mutate_billing_setup(
customer_id: customer_id,
operation: operation,
)
puts sprintf("Removed billing_setup %s", response.results.first.resource_name)
end
Перл
sub remove_billing_setup {
my ($api_client, $customer_id, $billing_setup_id) = @_;
# Create the resource name of a billing setup to remove.
my $billing_setup_resource_name =
Google::Ads::GoogleAds::V12::Utils::ResourceNames::billing_setup(
$customer_id, $billing_setup_id);
# Create a billing setup operation.
my $billing_setup_operation =
Google::Ads::GoogleAds::V12::Services::BillingSetupService::BillingSetupOperation
->new({
remove => $billing_setup_resource_name
});
# Remove the billing setup.
my $billing_setup_response = $api_client->BillingSetupService->mutate({
customerId => $customer_id,
operation => $billing_setup_operation
});
printf "Removed billing setup with resource name: '%s'.\n",
$billing_setup_response->{result}{resourceName};
return 1;
}