AdWords ve Merchant Center Alt Hesapları Oluşturma ve Bağlama

1. Giriş

Bu codelab'de, Content API for Shopping ve AdWords API ile çalışmanın bazı temel bilgilerini öğrenecek ve her ikisini de kullanan bir uygulama oluşturacaksınız. Özellikle, bir AdWords hesabı ve bir Merchant Center hesabı oluşturup bağlayacak bir komut satırı uygulaması oluşturacaksınız.

Neler öğreneceksiniz?

• Yönetici hesabı tarafından yönetilen AdWords hesapları oluşturma
• Çok müşterili hesap tarafından yönetilen Merchant Center hesapları oluşturma
• Merchant Center hesabından AdWords hesabına bağlantı isteğinde bulunma
• Bir AdWords hesabında bekleyen Merchant Center bağlantısını kabul etme

Gerekenler

• Bir AdWords yönetici hesabı
• Merchant Center çok müşterili hesabı
• Java 7 veya sonraki sürümler
• Maven
• Örnek kod
• Bir metin düzenleyici (Eclipse veya IntelliJ gibi Maven projelerini anlayan bir IDE önerilir)

2. Hazırlanma

Kodu indirin.

Bu codelab'deki tüm kodları indirmek için aşağıdaki bağlantıyı tıklayın:

Kaynak kodu indir

İndirilen ZIP dosyasını açın. Bu işlem, ihtiyacınız olacak tüm kaynaklarla birlikte bir Maven projesi içeren bir kök klasörü (shopping-account-linking-master) açar. Aşağıdaki alt dizinler özellikle dikkat çekicidir:

• src/main/java, Maven projesinin kaynak köküdür ve üzerinde çalışabileceğiniz bir kod iskeleti içerir.
• src/main/java/solution, tamamlanmış çözümü içerir.

Gerekli paketleri yükleme ve derleme

Eclipse veya IntelliJ gibi Maven'i destekleyen bir IDE kullanıyorsanız çıkarılan klasörü Maven projesi olarak içe aktarabilir ve projeyi normal şekilde derleyebilirsiniz.

Maven'ı komut satırından kullanıyorsanız gerekli paketleri almak ve projeyi açılan projenin kök klasöründen (shopping-account-linking-master) derlemek için aşağıdaki komutu çalıştırabilirsiniz:

mvn compile

3. Kimlik doğrulama ayarlama

Bu adımda herhangi bir kodlama yapmayacağız ancak AdWords API ve Alışveriş için Content API'ye yönelik uygun kimlik doğrulama jetonlarını içeren dosyalar oluşturacağız.

AdWords API kimlik doğrulamasını ayarlama

Bu codelab, istemci kitaplığıyla aynı kimlik bilgisi yüklemesini kullanır. Bu nedenle, yönetici hesabınızla Java için Google Ads API'leri İstemci Kitaplığı'nı daha önce kullandıysanız kurulumu tamamlamış olmanız gerekir. Aksi takdirde, Java için Google Ads API'leri istemci kitaplığını kullanmaya başlamak için 1-3 arasındaki adımları uygulayın.

Content API kimlik doğrulamasını ayarlama

Henüz bir hizmet hesabı anahtarınız yoksa:

1. Çok müşterili hesabınız için Merchant Center'a gidin ve taşma menüsünden Content API'yi seçin:
2. Kimlik doğrulama'yı seçin, ardından mavi + düğmesini tıklayın:
3. Google Cloud Platform ve Google API'leri Hizmet Şartları'nı kabul ettikten sonra tarayıcınız, yeni hizmet hesabı anahtarınızı içeren bir JSON dosyasını otomatik olarak indirir.

Şimdi, hizmet hesabı ile Alışveriş örnekleri için kimlik doğrulama ayarlama talimatlarını uygulayın. Yani hizmet hesabı anahtarınızın bir kopyası, ana dizininizden itibaren şu yolda bulunmalıdır: shopping-samples/content/service-account.json. Bu codelab'i tamamladıktan sonra örnekleri denemek istemiyorsanız örnek yapılandırmasını ayarlamanız gerekmez.

Test edin

Doğrulama jetonlarını doğru yerlere yerleştirdiğinize göre şimdi örnekleri çalıştırmayı deneyin. Komut satırında Maven kullanıyorsanız aşağıdaki komutları çalıştırın:

mvn compile

Not: src/main/resources içindeki dosyalardan herhangi birini değiştirirseniz (bu adımda olduğu gibi herhangi bir kod değişikliği yapmasanız bile) değiştirilen kaynaklarınızı hedefe kopyalamak için örnekleri çalıştırmadan önce yeniden derleyin.

mvn exec:java -Dexec.mainClass="SolutionRunner"

Oturum nesnelerinin sağlanmadığıyla ilgili bir hata mesajı alırsanız kimlik doğrulama jetonlarınız yerinde ve doğru şekilde çalışıyor demektir. Aksi takdirde, aldığınız hata mesajı hangi kimlik bilgilerinin çalışmadığını ve hangi dosyanın düzeltilmesi gerektiğini bildirir.

Önemli: Sağladığımız çerçeve, Content API hizmet hesabınızın yalnızca çok müşterili hesabınızda kullanıcı olarak listelendiğini varsayar. Hizmet hesabınızın birden fazla hesaba erişimi olduğunu belirten bir hata alırsanız yukarıdaki adımları uygulayarak çok müşterili hesabınıza özel bir hizmet hesabı anahtarı edinin.

4. API'lere bağlanma

Kullanacağımız iki API için geçerli kimlik doğrulama jetonlarınız olduğuna göre artık gerçek kodu doldurmaya başlayabiliriz. Kimlik doğrulama jetonlarımızı kullanarak oturum nesneleri oluşturmayla başlayacağız. Sonraki adımlarda, bu oturum nesnelerini kullanarak her API'nin sağladığı çeşitli hizmetlere ve yöntemlere erişeceğiz.

Content API oturum nesnesi oluşturma

Content API oturumu oluşturmak için ShoppingContent.Builder nesnesi oluşturup uygun ShoppingContent nesnesini oluşturmak için kullanacağız. Neyse ki ilki için ihtiyacımız olan her şey kod iskeletinde mevcut. Bu nedenle, aşağıdaki gibi bir araya getirmemiz yeterli:

SolutionRunner.java

// TODO(sessions): Create a ShoppingContent object using ShoppingContent.Builder.
contentApiSession =
    new ShoppingContent.Builder(httpTransport, jsonFactory, contentApiCredential)
        .setApplicationName("Linking AdWords and Merchant Center Accounts Codelab")
        .build();

Not: Bu ve sonraki kod örneklerindeki ilk yorumlar, kod iskeletinde zaten mevcuttur. Bu satırların nereye eklenmesi gerektiğini görmek için bunları bulun.

Ayrıca bu snippet'lerde kullandığımız AdWords API ve Content API sınıfları için gerekli olan tüm içe aktarma ifadelerini de çıkarıyoruz. Doğru içe aktarmaları otomatik olarak ekleyebilen bir IDE kullanmıyorsanız lütfen solution paketindeki kodu kontrol ederek gerekli içe aktarmaları bulun.

Uygulama adı ayarlamak kesinlikle gerekli değildir ancak build() yöntemi çağrılmadan önce ShoppingContent.Builder nesnesi aracılığıyla istenen seçeneklerin nasıl ayarlanacağını gösterir.

AdWords API oturum nesnesi oluşturma

Benzer şekilde, AdWordsSession nesneleri oluşturmak için AdWordsSession.Builder sınıfı vardır. Buradaki temel fark, yapılandırma seçeneklerini doğrudan oluşturucuda ayarlamak yerine, önceki adımda oluşturduğumuz ads.properties dosyasından yüklemek için fromFile() yöntemini kullanacak olmamızdır.

SolutionRunner.java

// TODO(sessions): Create a AdWordsSession object using AdWordsSession.Builder.
adWordsSession =
    new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(adwordsOAuth2Credential)
        .build();

Test edin

Maven projesini yeniden oluşturup çalıştırmak için son bölümdeki komutları kullanacağız.

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Bu kez herhangi bir hata almazsınız ancak ilginç bir çıkış da almazsınız. Yeni hesapları oluşturup bağlamak için API'leri çağırdığımızda bu bilgiyi ekleriz.

5. Yeni bir yönetilen AdWords hesabı oluşturma

API oturumu nesnelerimizi oluşturduğumuza göre, şimdi de bağlamak istediğimiz hesapları oluşturma işlemine geçeceğiz. AdWords ile başlayıp yönetici hesabımız altında bir test hesabı oluşturacağız.

Not: Bu bölümdeki tüm kod snippet'leri, iskelet kodunda aynı yere, sunuldukları sırayla eklenir. Bu nedenle, yalnızca yorumu (// TODO...)) gösteririz. Bu işaret, yorumların ilk videoda nereye yerleştirileceğini gösterir. Bu nedenle, bu ve sonraki adımlarda, giriş yorumu olmayan kod snippet'leri önceki snippet'in hemen ardından gelir.

ManagedCustomerService'e erişme

AdWords API'de, statik getInstance() yöntemini kullanarak önce AdWordsServices sınıfının bir örneğini alarak kullanılabilir çeşitli hizmetlere erişiriz. Bu örneği kullanarak, istemcinin oluşturulacağı oturum ve istenen hizmetin arayüzü olmak üzere iki bağımsız değişken alan get() yöntemiyle bu hizmetler için istemciler oluşturabiliriz.

SolutionRunner.java

// TODO(newAWaccount): Using the ManagedCustomerService, create a new testing AdWords account
// under the given manager account.

AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

ManagedCustomerServiceInterface managedCustomerService =
    adWordsServices.get(adWordsSession, ManagedCustomerServiceInterface.class);

Burada, belirli bir yönetici hesabından AdWords "müşterilerini" (hesaplarını) yönetmemize olanak tanıyan ManagedCustomerService'e erişiyoruz.

Yeni hesap ayarlarını belirtme

İlk olarak, yeni hesabımızın ayarlarını içeren bir ManagedCustomer nesnesi oluşturacağız. Bu codelab için bir test hesabı oluşturacağız. Hesabın para birimini ABD doları, saat dilimini ise ABD'nin batı yakasıyla aynı olarak ayarlayacağız.

SolutionRunner.java

Random rand = new Random();
long run = rand.nextLong();

ManagedCustomer newAdWordsAccount = new ManagedCustomer();
newAdWordsAccount.setName(String.format("AdWords Account Created by Run %d", run));
newAdWordsAccount.setTestAccount(true);
newAdWordsAccount.setCurrencyCode("USD");
newAdWordsAccount.setDateTimeZone("America/Los_Angeles");

Ayrıca, hesap adına eklediğimiz rastgele bir sayı oluştururuz. Bu yalnızca burada oluşturacağımız Google Ads hesabını daha sonra oluşturacağımız Merchant Center hesabıyla eşleştirebilmemiz içindir. Böylece çözümümüz tamamlandıktan sonra bunları görsel olarak inceleyebilir ve gerçekten de ikisini bağladığından emin olabiliriz.

Yeni yönetilen hesabı oluşturma

Yeni hesabı oluşturmak için ADD işlemini belirtmek üzere ManagedCustomerOperation kullanılır:

SolutionRunner.java

ManagedCustomerOperation operation = new ManagedCustomerOperation();
operation.setOperand(newAdWordsAccount);
operation.setOperator(Operator.ADD);

Ardından, ManagedCustomerService nesnesinin mutate() yöntemini kullanarak işlemi gerçekleştiririz. Bu yöntem, gerçekleştirilecek bir dizi işlem alır ancak burada yalnızca tek bir işlem gerçekleştirmek istiyoruz. mutate() yönteminin sonucu, ManagedCustomer listesini içeren bir değerdir. Burada, oluşturduğumuz yeni hesabı içeren bir müşteri listesi olacaktır. Bu yeni hesabın kimliğini gelecekte kullanmak üzere alırız ve çözümümüzün çıktısının bir parçası olarak görebilmek için yazdırırız.

SolutionRunner.java

ManagedCustomerReturnValue result =
    managedCustomerService.mutate(new ManagedCustomerOperation[] {operation});
Long adWordsId = result.getValue()[0].getCustomerId();
System.out.printf("Created new AdWords account %d%n", adWordsId);

Test edin

Daha önce olduğu gibi çözümü çalıştırmayı deneyin. Maven'i komut satırından kullanıyorsanız:

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Her şey yolunda giderse hata görmeye devam etmemeniz gerekir. Bu kez, oluşturduğumuz yeni AdWords hesabının kimliğini görürüz. Yönetici hesabınız için AdWords sitesini kontrol edin. Yeni hesabın burada da listelendiğini görürsünüz.

Not: Bu noktada, çözümün her çalıştırılması yeni hesaplar oluşturur. Çözümünüzü çalıştırmayı tamamladıktan sonra oluşturulan tüm AdWords hesaplarını AdWords sitesinden iptal edebilirsiniz. Sonuçta, bu hesaplar için adlandırma şemamız, hangilerinin kodumuz tarafından oluşturulduğunu görmeyi kolaylaştırıyor.

6. Yeni bir Merchant Center alt hesabı oluşturma

Bu adımda, son adımda oluşturduğumuz Google Ads hesabına bağlayacağımız Merchant Center alt hesabını oluşturacağız. Alt hesabı oluşturduktan sonra bağlantı isteğinde bulunmak yerine, ilgili AdWords hesabının kimliğine sahip olduğumuz için oluşturma sırasında bağlantı isteğinde bulunabiliriz.

Yeni alt hesabın ayarlarını belirtin

AdWords API'nin aksine, Account model sınıfının ayarlayıcıları nesneyi döndürür. Bu nedenle, çağrılarımızı yeni Account nesnesinde zincirleyebiliriz. Google Ads hesabı oluşturma sırasında oluşturduğumuz rastgele sayıyı, yeni Merchant Center hesabının adında da kullanırız.

SolutionRunner.java

Account newMcAccount = new Account()
    .setName(String.format("Merchant Center Account Created by Run %d", run))
    .setAdwordsLinks(
        ImmutableList.of(
            new AccountAdwordsLink()
                .setAdwordsId(BigInteger.valueOf(adWordsId))
                .setStatus("active")));

Bu adımın girişinde belirtildiği gibi, yeni yönetilen hesabın AdWords kimliğine zaten sahip olduğumuz için bu kimliği yeni alt hesabın AdwordsLinks listesine ekleyebiliriz. Yeni alt hesap oluşturulduğunda bu bağlantı otomatik olarak istenir ve AdWords API'de kullanılabilir.

Yeni alt hesabı oluşturun

Content API'de, Accounts hizmetine erişmek için oturum nesnesinin accounts() yöntemini çağırırız ve ardından bir işlem nesnesi oluşturmak yerine doğrudan insert() yöntemini çağırırız. Bu yöntemde iki bağımsız değişken kullanılır: yeni alt hesabın oluşturulacağı çok müşterili hesabın kimliği ve istenen ayarları içeren Account nesnesi:

SolutionRunner.java

newMcAccount = contentApiSession.accounts().insert(mcaId, newMcAccount).execute();

System.out.printf("Created new Merchant Center account %s%n", newMcAccount.getId());

insert() yöntemi, yeni alt hesabın ayarlarını içeren bir Account nesnesi döndürür. Döndürülen sürümde önemli bir bilgi (yeni alt hesabın kimliği) yer aldığından orijinal Account nesnemizin üzerine yazıyoruz. Bunu çözümümüzün çıktısında yazdırırız. Böylece çözümümüzü çalıştırabilir ve ardından yeni alt hesabın Merchant Center'da mevcut olduğunu doğrulayabiliriz.

Test edin

Daha önce olduğu gibi çözümü çalıştırmayı deneyin. Maven'i komut satırından kullanıyorsanız:

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Her şey yolunda giderse hata görmeye devam etmezsiniz ve bu kez hem yeni AdWords hesabının hem de yeni Merchant Center hesabının kimliklerini görürüz. Yeni alt hesabı görmek için çok müşterili hesabınızın Merchant Center bölümünü kontrol edin.

Not: AdWords'de olduğu gibi, çözümün her çalıştırılması artık yeni Merchant Center hesapları oluşturacaktır. Çözümünüzü çalıştırmayı tamamladıktan sonra oluşturulan tüm alt hesapları Merchant Center üzerinden silebilirsiniz.

7. AdWords hesabından gelen bağlantıyı kabul etme

Son adımda, yeni bir Merchant Center alt hesabı oluşturup aynı anda yeni AdWords hesabımıza bağlantı isteğinde bulunduk. Bu adımda, istenen bağlantıyı kabul etmek için AdWords API'yi kullanarak işlemi tamamlayacağız.

CustomerService'e erişin.

Daha önce olduğu gibi, AdWordsServices sınıfını kullanarak CustomerService için bir istemci alacağız. Ancak, istemciyi oluşturmadan önce AdWords oturum nesnemizi değiştirerek gelecekteki kullanımların yönetici hesabı yerine yeni yönetilen hesapta çalışmasını sağlıyoruz. Sonuçta, Merchant Center hesabı yönetici hesabına değil yönetilen hesaba bağlantı isteğinde bulunmuştu.

SolutionRunner.java

// TODO(acceptLink): Using the mutateServiceLinks method in CustomerService, accept the
// proposed link between the new AdWords account and the new Merchant Center account.

adWordsSession.setClientCustomerId(adWordsId.toString());

CustomerServiceInterface customerService =
    adWordsServices.get(adWordsSession, CustomerServiceInterface.class);

İstenen bağlantıyı belirtme

Yeni bir AdWords hesabı oluşturduğumuzda olduğu gibi, bağlantı ayarlarını içeren bir ServiceLink nesnesi ve ardından istenen işlemi açıklayan bir ServiceLinkOperation nesnesi oluştururuz. Burada, bekleyen hizmet bağlantısını bir MERCHANT_CENTER hesabına götürmek ve ACTIVE ile SET yapmak istiyoruz. serviceLinkId ayarı için, Google Ads'deki hizmet bağlantısının kimliği olarak kullanılan, yeni oluşturduğumuz Merchant Center hesabının kimliğini kullanacağız.

SolutionRunner.java

ServiceLink serviceLink = new ServiceLink();
serviceLink.setServiceLinkId(newMcAccount.getId().longValue());
serviceLink.setLinkStatus(ServiceLinkLinkStatus.ACTIVE);
serviceLink.setServiceType(ServiceType.MERCHANT_CENTER);

ServiceLinkOperation op = new ServiceLinkOperation();
op.setOperator(Operator.SET);
op.setOperand(serviceLink);

Bağlantıyı kabul etme

Son olarak, işlemi gerçekleştirmek için CustomerService nesnesinin mutateServiceLinks() yöntemini çağıracağız. Daha önce olduğu gibi, bir dizi hizmet bağlantısı işlemi gerekir. Bu kez yöntem, (muhtemelen değiştirilmiş) hizmet bağlantılarının listesini doğrudan döndürüyor. Bu nedenle, bu listede döngü oluşturarak çözümümüzün sonucunu yazdıracağız. Elbette, yalnızca tek bir işlem belirttiğimiz için çıktıda yalnızca tek bir bağlantının yazdırılmasını beklersiniz.

SolutionRunner.java

ServiceLink[] mutatedServiceLinks =
    customerService.mutateServiceLinks(new ServiceLinkOperation[] {op});
for (ServiceLink mutatedServiceLink : mutatedServiceLinks) {
  System.out.printf(
      "Service link with service link ID %d, type '%s' updated to status: %s.%n",
      mutatedServiceLink.getServiceLinkId(),
      mutatedServiceLink.getServiceType(),
      mutatedServiceLink.getLinkStatus());
}

Test edin

Daha önce olduğu gibi çözümü çalıştırmayı deneyin. Maven'i komut satırından kullanıyorsanız:

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Her şey yolunda giderse hata görmeye devam etmezsiniz. Bu kez, hizmet bağlantısının etkin olacak şekilde güncellendiğine dair bir not da görürsünüz. AdWords ve Merchant Center'ı kontrol edin ve hesapların gerçekten bağlanıp bağlanmadığını tekrar kontrol edin.

8. Bir tema üzerinde varyasyonlar

Codelab'i tamamladığınız için tebrikler. Artık tam olarak çalışan bir çözümünüz olduğuna göre, bu çözümde gördüğünüz API'lerin daha fazlasını kullanmak için çözümü nasıl değiştirebileceğinize veya genişletebileceğinize dair bazı örneklere göz atalım.

Ek bilgi: AdWords bağlantısı isteğinde bulunmak için mevcut bir Merchant Center hesabını güncelleme

Bu codelab'de, Merchant Center hesabını oluştururken bağlantı isteğinde bulunmak için AdWords hesabının bilgilerini kullanabilmek amacıyla AdWords hesabını önce oluşturduk. Ancak Merchant Center hesabı zaten varsa bunun yerine yapılandırmasını güncellemeniz gerekir. Önce Merchant Center hesabını oluşturmak için kodunuzu değiştirmeyi deneyin. Ardından, AdWords hesabını oluşturduktan sonra geri dönüp bağlantı isteğinde bulunmak için yapılandırmasını güncelleyin.

Not: Accounts.update veya Accounts.patch yöntemlerinden birini kullanmanız gerekir. Hatta aradaki farkı anlamak için her biriyle bir sürüm deneyin.

Önemli: Accounts.insert çağrısından hemen sonra yeni bir Merchant Center hesabı kullanılamayabilir. Yeni hesap kullanıma sunulana kadar, hesaba erişme veya hesabı değiştirme girişimlerinde 401 HTTP hatası alırsınız. Alışveriş örneklerinde, BaseWorkflowSample.java içindeki retryFailures yöntemini kullanan AccountWorkflow.java içinde yöntemleri yeniden denemek için eksponansiyel geri yükleme kullanma örneği verilmiştir.

Ekstra bilgi: AdWords ve Merchant Center hesap bilgilerini alarak bağlantı oluşturma işlemini doğrulama

Şu anda uygulama, yalnızca API çağrılarında hata olmamasını başarı işareti olarak kabul etmektedir. Yeni Merchant Center ve AdWords hesaplarının bağlantı bilgilerini kontrol etmek için örneği genişletmeyi deneyin ve bağlantının gerçekten etkin olduğunu görün.

Not: Content API tarafında Accounts.get yöntemine bakmanız gerekir. AdWords tarafında, CustomerServiceInterface nesnesinin getServiceLinks yöntemini kullanmanız gerekir.

Dünyanızı keşfedin

Yapabileceğiniz başka değişiklikler olduğunu düşünüyorsanız bunları da deneyin. Fikirleriniz için referans koduna ihtiyacınız varsa Google Alışveriş örnekleri ile Google Ads Java istemci kitaplığı kaynağındaki examples dizinine göz atın.