Mengelola hubungan akun

Anda dapat menggunakan Accounts API untuk mengelola hubungan antara akun Merchant Center Anda dan penyedia layanan lainnya. Hubungan adalah koneksi formal yang memungkinkan penyedia menawarkan layanan tertentu kepada bisnis Anda. Layanan menentukan izin dan kemampuan yang diberikan kepada penyedia, seperti pengelolaan produk atau pengelolaan kampanye. Misalnya, menautkan akun Merchant Center ke akun Google Ads memungkinkan akun Google Ads menggunakan data produk Anda untuk menjalankan kampanye iklan.

Hubungan terdiri dari atribut berikut:

• Akun Merchant Center yang menerima layanan
• Penyedia layanan
• Layanan atau kumpulan layanan yang diberikan ke akun Merchant Center

Alias

Penyedia layanan dapat mengaitkan alias dengan akun yang mereka layani (ini setara dengan kolom seller_id yang ada di resource account di Content API for Shopping). Alias dapat ditetapkan menggunakan kolom account_id_alias opsional dalam resource AccountRelationship dan berfungsi sebagai ID kustom. Alias harus terdiri dari 1 hingga 50 karakter yang dipilih dari huruf ASCII, angka desimal, tanda hubung, garis bawah, titik, atau tilde ([A-Za-z0-9_~.-]{1,50}).

Struktur URL untuk mengakses akun menggunakan aliasnya adalah GET /accounts/v1/accounts/{provider}~{account_id_alias}.

Layanan

Di Accounts API, akun dapat menerima layanan berikut. Anda dapat menambahkan banyak layanan ini selama pembuatan akun.

• Agregasi akun: Layanan ini (accountAggregation) menautkan akun tingkat lanjut multiklien ke sub-akun, sehingga memberikan akses penuh dan tidak terbatas ke akun tingkat lanjut dan membuat sub-akun terlihat di UI Merchant Center. UI Merchant Center otomatis mengonversi akun menjadi akun tingkat lanjut dengan accountAggregation untuk pembuat toko (platform e-commerce), partner saluran, marketplace, retailer multi-merek, dan retailer internasional saat membuat sub-akun baru. Jika Anda adalah agensi, gunakan accountManagement. Saat Anda membuat akun menggunakan agregasi akun, externalAccountId harus dihilangkan.

• Pengelolaan kampanye: Layanan ini memodelkan penautan antara akun Merchant Center dan akun Google Ads, sehingga akun Google Ads dapat mengakses data produk dan akun yang diperlukan untuk menjalankan kampanye iklan. Penyedia layanan dalam hal ini adalah GOOGLE_ADS dan externalAccountId adalah ID akun Google Ads. Layanan ini juga dapat diusulkan ke akun yang ada.

• Layanan ini memungkinkan pembuatan filter produk khusus partner saat menjalankan kampanye Jaringan Media Commerce.
• Saat ini, Anda harus menggunakan sub-API Accounts versi Alfa.
• Penggunaan fitur ini memerlukan izin khusus GMC.

Hubungi tim pengelolaan akun Google Ads Anda untuk mengetahui detail selengkapnya.

• Perbandingan belanja: Ini menunjukkan hubungan dengan Layanan Perbandingan Belanja (CSS) yang mengoperasikan akun Merchant Center.

• Pengelolaan listingan lokal: Ini mewakili hubungan dengan pengelola toko untuk mengelola inventaris lokal dan listingan menggunakan Google Profil Bisnis.

• Pengelolaan akun: Layanan ini (accountManagement) memungkinkan penyedia melakukan tindakan administratif di akun Merchant Center eksternal mandiri, seperti mengonfigurasi setelan akun, mengelola pengguna, atau memperbarui informasi bisnis. Bisnis juga dapat membatasi akses yang diberikan. Saat digunakan selama pembuatan akun, layanan ini membuat akun mandiri yang ditautkan ke penyedia. Perubahan ini juga dapat diusulkan ke akun yang ada. Agensi yang menggunakan jenis layanan ini dapat melihat akun yang mereka kelola di Merchant Center untuk Agensi. Pembuat toko dan partner saluran dapat menggunakan Merchant API untuk mengambil informasi tentang penjual yang mereka kelola melalui accountManagement.

• Pengelolaan produk: Layanan ini memungkinkan penyedia mengelola produk dan fitur terkait seperti sumber data dan aturan. Jika ditambahkan selama pembuatan akun, biasanya dikombinasikan dengan accountManagement atau accountAggregation. Layanan ini juga dapat diusulkan ke akun yang ada.

• Pengelolaan checkout UCP (v1alpha, akses terbatas): Layanan ucpCheckoutManagement memungkinkan penyedia layanan yang disetujui mengelola integrasi, setelan, dan partisipasi program checkout UCP atas nama penjual. Layanan ini hanya dapat diusulkan atau disetujui oleh akun Merchant Center yang ada.

  Catatan: Checkout UCP adalah fitur alfa dengan akses terbatas. Pelajari lebih lanjut penyedia layanan dan checkout UCP di Merchant Center untuk penyedia layanan.

Bersalaman

Untuk membuat layanan, akun yang menyediakan layanan dan akun yang menerima layanan harus mengizinkan koneksi. Proses otorisasi ini disebut handshake.

Handshake adalah proses dua langkah:

1. Satu pihak mengusulkan link layanan.
2. Pihak lain menyetujui atau menolak proposal.

Setelah proposal diterima, layanan akan disetujui dan dianggap telah sepenuhnya ditetapkan. Setiap hak akses yang diberikan kepada penyedia layanan kini diberikan kepada pengguna yang memenuhi syarat (Lihat hak akses di bawah).

Perhatikan bahwa pengguna yang membuat, menolak, atau menyetujui proposal harus memiliki hak akses ADMIN di akun yang memulai proses. Jadi, jika penyedia layanan mengajukan layanan, pengguna yang membuat proposal harus merupakan ADMIN di akun penyedia layanan dan pengguna yang menerima atau menolak proposal harus merupakan ADMIN di akun penerima.

Contoh berikut menunjukkan cara mengusulkan layanan akun:

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.AccountName;
import com.google.shopping.merchant.accounts.v1.AccountService;
import com.google.shopping.merchant.accounts.v1.AccountServicesServiceClient;
import com.google.shopping.merchant.accounts.v1.AccountServicesServiceSettings;
import com.google.shopping.merchant.accounts.v1.ProductsManagement;
import com.google.shopping.merchant.accounts.v1.ProposeAccountServiceRequest;
import shopping.merchant.samples.utils.Authenticator;

/** This class demonstrates how to propose a service to an existing Merchant Center account. */
public class ProposeServiceSample {

  public static void proposeService(long accountId, long providerId, String externalAccountId)
      throws Exception {

    // Obtains OAuth token based on the user's configuration.
    // The user that authenticates should have access to the account.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    AccountServicesServiceSettings accountServicesServiceSettings =
        AccountServicesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Calls the API and catches and prints any network failures/errors.
    try (AccountServicesServiceClient accountServicesServiceClient =
        AccountServicesServiceClient.create(accountServicesServiceSettings)) {

      // The service to be proposed.
      // This sample shows how to propose product management.
      // For more information about the different services, see:
      // https://developers.google.com/merchant/api/guides/accounts/services
      AccountService accountService =
          AccountService.newBuilder()
              .setProductsManagement(ProductsManagement.newBuilder().build())
              .setExternalAccountId(externalAccountId)
              .build();

      String accountName =
          AccountName.newBuilder().setAccount(String.valueOf(accountId)).build().toString();

      ProposeAccountServiceRequest request =
          ProposeAccountServiceRequest.newBuilder()
              .setParent(accountName)
              .setProvider("accounts/" + providerId)
              .setAccountService(accountService)
              .build();

      System.out.println("Sending Propose Service request:");
      AccountService response = accountServicesServiceClient.proposeAccountService(request);

      System.out.println("Proposed Service below");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    // The ID of the account to propose the service to.
    long accountId = 123L;
    // This is the provider ID of the e-commerce platform.
    long providerId = 456L;
    // An external ID that uniquely identifies the account service.
    String externalAccountId = "ext-acc-id-123";
    proposeService(accountId, providerId, externalAccountId);
  }
}
ProposeServiceSample.java

require_once __DIR__ . '/../../../../vendor/autoload.php';
require_once __DIR__ . '/../../../Authentication/Authentication.php';
require_once __DIR__ . '/../../../Authentication/Config.php';

use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1\AccountAggregation;
use Google\Shopping\Merchant\Accounts\V1\AccountService;
use Google\Shopping\Merchant\Accounts\V1\Client\AccountServicesServiceClient;
use Google\Shopping\Merchant\Accounts\V1\ProposeAccountServiceRequest;

/**
 * This class demonstrates how to propose an account service.
 */
class ProposeAccountServiceSample
{
    /**
     * A helper function to create the account name string.
     *
     * @param string $accountId The ID of the account.
     *
     * @return string The account name has the format: `accounts/{account_id}`
     */
    private static function toAccountName(string $accountId): string
    {
        return sprintf('accounts/%s', $accountId);
    }

    /**
     * Proposes a new account service.
     *
     * @param array $config The configuration data used for authentication and
     *     getting the account ID.
     * @param string $providerId The ID of the provider account.
     */
    public static function proposeAccountService(
        array $config,
        string $providerId
    ): void {
        // Gets the OAuth credentials to make the request.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Creates options containing credentials for the client to use.
        $options = ['credentials' => $credentials];

        // Creates a client.
        $accountServicesServiceClient = new AccountServicesServiceClient($options);

        // Calls the API and catches and prints any network failures/errors.
        try {
            $accountAggregation = new AccountAggregation();
            $accountService = (new AccountService())
                ->setAccountAggregation($accountAggregation);

            $request = (new ProposeAccountServiceRequest())
                ->setParent(self::toAccountName($config['accountId']))
                ->setProvider(self::toAccountName($providerId))
                ->setAccountService($accountService);

            print "Sending Propose AccountService request\n";
            $response = $accountServicesServiceClient->proposeAccountService($request);
            print "Proposed AccountService below\n";
            print $response->serializeToJsonString(true) . PHP_EOL;
        } catch (ApiException $e) {
            printf("An error has occurred: %s%s", $e->getMessage(), PHP_EOL);
        }
    }

    /**
     * Helper to execute the sample.
     */
    public function callSample(): void
    {
        $config = Config::generateConfig();

        // Update this with the Merchant Center provider ID you want to get the
        // relationship for.
        $providerId = 111;
        self::proposeAccountService($config, $providerId);
    }
}

// Run the script
$sample = new ProposeAccountServiceSample();
$sample->callSample();
ProposeAccountServiceSample.php

"""This class demonstrates how to propose an account service."""

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1 import AccountAggregation
from google.shopping.merchant_accounts_v1 import AccountService
from google.shopping.merchant_accounts_v1 import AccountServicesServiceClient
from google.shopping.merchant_accounts_v1 import ProposeAccountServiceRequest

_ACCOUNT = configuration.Configuration().read_merchant_info()
_PARENT = f"accounts/{_ACCOUNT}"


def propose_account_service(provider_id: int) -> None:
  """Proposes an account service.

  Args:
    provider_id: The Merchant Center ID of the provider.
  """
  # Gets OAuth Credentials.
  credentials = generate_user_credentials.main()

  # Creates a client.
  client = AccountServicesServiceClient(credentials=credentials)

  # Creates the provider resource name from the provider ID.
  provider = f"accounts/{provider_id}"

  # Creates an AccountService object.
  # For this request, only `account_aggregation` is needed.
  account_service = AccountService()
  account_service.account_aggregation = AccountAggregation()

  # Creates the request.
  request = ProposeAccountServiceRequest(
      parent=_PARENT,
      provider=provider,
      account_service=account_service,
  )

  # Makes the request and catches and prints any error messages.
  try:
    print("Sending Propose AccountService request")
    response = client.propose_account_service(request=request)
    print("Proposed AccountService below")
    print(response)
  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  # Update this with the Merchant Center provider ID you want to get the
  # relationship for.
  provider_id_ = 111
  propose_account_service(provider_id_)
propose_account_service_sample.py

Perilaku handshake khusus layanan

Berikut adalah deskripsi persyaratan handshake khusus untuk setiap layanan:

• Agregasi akun: Layanan ini hanya dapat dibuat sebagai bagian dari pembuatan akun. Penyedia layanan diharapkan merupakan akun tingkat lanjut, dan layanan akan otomatis disetujui karena pengguna akun tingkat lanjut memiliki akses ADMIN penuh ke akun yang sedang dibuat.

• Perbandingan belanja: Layanan ini otomatis disetujui saat ditambahkan selama pembuatan akun menggunakan createAndConfigure.

• Pengelolaan kampanye: Meskipun mengikuti proses handshake normal, proposal dibuat di satu sistem (misalnya Google Ads) dan persetujuan dilakukan di sistem lain (misalnya di Merchant Center atau melalui Merchant API).

• Pengelolaan listingan lokal: Untuk layanan ini, handshake diusulkan dalam metode khusus dan persetujuan dilakukan di sistem lain (misalnya Google Profil Bisnis). Langkah-langkah mendetailnya ada di Panduan untuk menautkan Google Profil Bisnis.

• Pengelolaan akun: Untuk layanan ini, proses handshake reguler berlaku saat menggunakan propose. Jika layanan ditambahkan selama pembuatan akun menggunakan createAndConfigure, layanan tersebut akan otomatis disetujui.

• Pengelolaan produk: Untuk layanan ini, proses handshake reguler berlaku (diusulkan oleh satu pihak, diikuti dengan penerimaan dari pihak lain).

• Pengelolaan checkout UCP (v1alpha, akses terbatas): Untuk layanan ini, penjual dapat menyelesaikan handshake melalui dialog penautan akun yang dihosting oleh Google di portal penyedia layanan, atau menggunakan proses handshake standar (propose diikuti dengan approve). Untuk mengetahui detail integrasi, lihat dokumentasi penyedia layanan Merchant Center.

Hak akses

Setiap jenis layanan memberikan tingkat akses tertentu bagi pengguna penyedia layanan atas akun yang dilayani:

• Agregasi akun: Layanan ini memberikan hak ADMIN penuh.

• Pengelolaan kampanye: Layanan ini memberikan hak akses terbatas, sehingga akun Google Ads terkait dapat mengakses produk dan informasi akun dasar.

• Perbandingan belanja: Layanan ini, secara default, memberikan hak ADMIN penuh. Namun, bisnis dapat membatasi akses yang diberikan di Merchant Center.

• Pengelolaan listingan lokal: Layanan ini tidak memberikan hak akses langsung. Namun, hal ini memungkinkan listingan menyinkronkan produknya dengan akun Merchant Center.

Penting: Hak akses yang dijelaskan untuk jenis layanan berikut hanya berlaku untuk penyedia layanan yang disetujui. Hubungi tim dukungan kami jika Anda adalah penyedia layanan dan ingin menggunakan kemampuan ini. Jika sebelumnya Anda telah disetujui untuk menggunakan metode accounts.link untuk pengelolaan produk di Content API for Shopping, Anda dapat menggunakan layanan ini di Merchant API tanpa persetujuan lebih lanjut.

• Pengelolaan akun: Layanan ini, secara default, memberikan hak ADMIN penuh.

• Pengelolaan produk: Layanan ini memberikan hak ADMIN penuh. Perhatikan bahwa pada masa mendatang, hal ini akan dibatasi hanya untuk hak akses terkait produk.

• Pengelolaan checkout UCP (v1alpha, akses terbatas): Layanan ini memberikan hak ADMIN penuh. Perhatikan bahwa pada masa mendatang, hal ini akan dibatasi hanya untuk hak akses terkait checkout UCP.

Cara penerapan hubungan untuk platform pihak ketiga

Jika Anda adalah platform pihak ketiga yang mengelola akun atas nama bisnis lain, berikut adalah cara berbagai konsep dipetakan ke struktur akun Anda:

1. Penyedia layanan: Akun lanjutan Anda.
2. Akun yang menerima layanan: Akun Merchant Center yang mewakili bisnis yang Anda kelola.
3. Layanan:
   • accountAggregation: Digunakan oleh pembuat toko (platform e-commerce), partner saluran, marketplace, dan retailer multi-merek yang membuat sub-akun baru atas nama penjual. UI Merchant Center otomatis mengonfigurasi pembuat toko dan partner saluran sebagai akun tingkat lanjut dengan accountAggregation, sehingga mereka dapat melihat dan mengelola sub-akun di UI Merchant Center.
   • accountManagement: Digunakan oleh agensi yang membuat atau menautkan ke akun klien mandiri yang dimiliki oleh penjual, yang dapat mereka lihat di Merchant Center untuk Agensi. Jenis penyedia layanan lainnya menggunakan metode accounts.list di Merchant API untuk melihat informasi akun tertaut.

Untuk mengetahui detail tentang cara menyiapkan akun tingkat lanjut dan menautkan ke akun Merchant Center baru, lihat Membuat akun.