Konfiguracja płatności

Konfiguracja płatności to połączenie na poziomie konta Google Ads i konta płatności (nazywane też fakturą), które określa, kto jest obciążany kosztami ponoszonymi przez budżety konta rozliczeniowego. Każde konto płatności odpowiada jednej fakturze.

Informacje o kontach płatności

Każdy BillingSetup określa konto płatności, które jest fakturowane na podstawie kosztów poniesionych przez budżety konta. To konto płatności jest powiązane z profilem płatności, który ostatecznie odpowiada za obciążenia.

Konfiguracje płatności zawierają pola payments_account oraz grupę pól payments_account_info, które identyfikują używane konto płatności. Należą do nich:

Jeśli konto płatności kwalifikuje się do płatności skonsolidowanych, kilka kont Google Ads można zgrupować na tej samej fakturze, ustawiając konfigurację płatności tak, aby wykorzystywała to samo konto płatności.

Tworzenie nowych konfiguracji płatności

Nowe konfiguracje płatności możesz połączyć z dotychczasowymi lub utworzonymi w tym samym czasie kontami płatności.

Korzystanie z istniejącego konta płatności

Aby połączyć z istniejącym kontem płatności, ustaw dla zasobu payments_account identyfikator zasobu prawidłowego konta płatności. Pamiętaj jednak o modyfikowaniu wartości payments_account_info.

Dostępne konta płatności możesz wymienić za pomocą metody PaymentsAccountService.ListPaymentsAccounts. Zwracany błąd PaymentsAccounts zależy od konta menedżera, którego używasz do uwierzytelniania.

Każdy identyfikator PaymentsAccount musi mieć identyfikator konta menedżera dokonującego płatności w polu paying_manager_customer.

Korzystanie z nowego konta płatności

Aby połączyć je z nowym kontem płatności, ustaw te pola w kolumnie payments_account_info (Don't setpayments_account):

Poniższy przykład pokazuje, jak utworzyć nową konfigurację płatności na podstawie istniejącego identyfikatora profilu płatności. Jak wspomnieliśmy wcześniej, utworzymy też nowe konto płatności o nazwie 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);
}

Jeśli jest to pierwsza konfiguracja płatności dodana do konta Google Ads, klient skutecznie zarejestruje się, używając wskazanego profilu płatności.

Stan konfiguracji płatności

Nowe instancje BillingSetup muszą zostać zatwierdzone, zanim zaczną obowiązywać. Do tego czasu status jest w stanie PENDING.

BillingSetup może być w jednym z tych typów znaczników status:

Stan konfiguracji płatności Opis
PENDING Czeka na zatwierdzenie.
APPROVED_HELD Zaakceptowano, ale odpowiadający mu pierwszy budżet nie. Może się tak zdarzyć tylko w przypadku konfiguracji płatności skonfigurowanych do fakturowania miesięcznego.
APPROVED Konfiguracja została zatwierdzona.
CANCELLED Użytkownik anulował konfigurację przed zatwierdzeniem.

Pobieram konfigurację płatności na koncie

Podobnie jak większość innych elementów interfejsu Google Ads API, BillingSetup jest pobierany przez zapytanie GoogleAdsService.SearchStream, który korzysta z zapytania Google Ads Language Language, które pola zwracają dane.

Java

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());
    }
  }
}
      

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsServiceClient.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V11.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
        );
    }
}
      

Python

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

Ruby

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
      

Perl

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::V11::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;
}
      

Gdy otrzymasz odniesienie do elementu BillingSetup, możesz go użyć do utworzenia AccountBudgetProposal zgodnie z opisem w sekcji Budżet konta.

Anulowanie oczekującej konfiguracji płatności

BillingSetup, który nie został jeszcze zastosowany, można anulować, korzystając z operacji usuwania. Konfiguracje płatności można anulować tylko wtedy, gdy ich ustawienia status to PENDING lub APPROVED i zaczną się w przyszłości.

Java

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());
  }
}
      

C#

public void Run(GoogleAdsClient client, long customerId, long billingSetupId)
{
    // Get the BillingSetupServiceClient.
    BillingSetupServiceClient billingSetupService = client.GetService(
        Services.V11.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
    );
}
      

Python

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

Ruby

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
      

Perl

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::V11::Utils::ResourceNames::billing_setup(
    $customer_id, $billing_setup_id);

  # Create a billing setup operation.
  my $billing_setup_operation =
    Google::Ads::GoogleAds::V11::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;
}