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

1. Giriş

Bu codelab'de, Alışveriş için Content API ve AdWords API ile çalışmayla ilgili bazı temel bilgileri öğrenecek ve her ikisini de kullanan bir uygulama oluşturacaksınız. Özellikle, bir AdWords hesabı ve 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.
• AdWords hesabında beklemede olan bir Merchant Center bağlantısını kabul etme.

Gerekenler

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

2. Hazırlanma

Kodu indirin

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

Kaynak kodu indir

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

• 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 uyumlu bir IDE kullanıyorsanız ayıklanan klasörü Maven projesi olarak içe aktarabilir ve ardından projeyi normal şekilde derleyebilirsiniz.

Maven'i komut satırından kullanıyorsanız gerekli paketleri almak ve projeyi, paketi açtığınız 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ğrulamayı ayarlama

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

AdWords API kimlik doğrulamasını ayarlama

Bu kod laboratuvarında, istemci kitaplığıyla aynı kimlik bilgisi yükleme yöntemi kullanılır. Bu nedenle, yönetici hesabınızla Java için Google Ads API'leri istemci kitaplığını daha önce kullandıysanız gerekli ayarları yapmış olmanız gerekir. Aksi takdirde, Java için Google Ads API'leri istemci kitaplığını kullanmaya başlama ile ilgili 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ın Merchant Center'ına 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.

Ardından, Alışveriş örnekleri için hizmet hesabıyla kimlik doğrulamayı ayarlama talimatlarını uygulayın. Yani, hizmet hesabı anahtarınızın bir kopyası ana dizininizdeki şu yolda bulunmalıdır: shopping-samples/content/service-account.json. Bu codelab'i tamamladıktan sonra örnekleri denemek istemiyorsanız örnekler yapılandırmasını ayarlamanıza gerek yoktur.

Test edin

Doğru konumlarda kimlik doğrulama jetonlarınız olduğu için ö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) 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 yerindedir ve düzgün çalışıyordur. Aksi takdirde, aldığınız hata mesajında hangi kimlik bilgilerinin çalışmadığı ve hangi dosyanın düzeltilmesi gerektiği belirtilir.

Ö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ği varsaymaktadır. Hizmet hesabınızın birden fazla hesaba erişimi olduğunu belirten bir hata alırsanız yukarıdaki adımları uygulayarak özellikle çok müşterili hesabınız için bir hizmet hesabı anahtarı edinin.

4. API'lere bağlanma

Kullanacağımız iki API için geçerli kimlik doğrulama jetonlarına sahip olduğunuza göre asıl kodu doldurmaya başlayalım. Kimlik doğrulama jetonlarımızı kullanarak oturum nesneleri oluşturarak başlayacağız. Sonraki adımlarda, bu oturum nesnelerini kullanarak her API'nin sunduğu çeşitli hizmetlere ve yöntemlere erişeceğiz.

Content API oturum nesnesi oluşturma

Content API oturumu oluşturmak için bir ShoppingContent.Builder nesnesi oluşturup uygun ShoppingContent nesnesini oluşturmak için kullanırız. Neyse ki birincisini oluşturmak için ihtiyacımız olan her şey kod iskeletinde zaten mevcut. Dolayısıyla, bunları 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 ekleneceğini görmek için bunları arayın.

Ayrıca bu snippet'lerde kullandığımız AdWords API ve Content API sınıfları için gerekli tüm içe aktarma beyanları da atlanır. Doğru içe aktarma işlemlerini otomatik olarak ekleyebilecek bir IDE kullanmıyorsanız lütfen gerekli içe aktarma işlemleri için solution paketindeki kodu kontrol edin.

Uygulama adı belirlemek zorunlu 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 bir 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 kullanacağımı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şturmak ve çalıştırmak için (komut satırından çalıştırıyorsanız) son bölümdeki komutları kullanacağız:

mvn compile

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

Bu sefer hiç hata almayacaksınız ancak ilginç bir sonuç da almayacaksınız. Yeni hesapları oluşturup bağlamak için API'leri çağırdığımızda bunu ekleriz.

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

API oturum nesnelerimizi oluşturduğumuza göre, bağlamak istediğimiz hesapları oluşturmaya geçebiliriz. 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, sunulan sırayla iskelet kodunun aynı yerine eklenir. Bu nedenle, yalnızca ilkinde nereye yerleştirileceğini belirten yorumu (// TODO...)) gösteririz. Bu ve sonraki adımlarda, giriş yorumu olmayan kod snippet'leri görürseniz bunlar önceki snippet'ten hemen sonra gelir.

ManagedCustomerService'e erişim

AdWords API'de, statik getInstance() yöntemini kullanarak önce AdWordsServices sınıfının bir örneğini alarak çeşitli mevcut hizmetlere erişiriz. Bu örneği kullanarak, get() yöntemi aracılığıyla bu hizmetler için istemciler oluşturabiliriz. Bu yöntem iki bağımsız değişken alır: istemcinin oluşturulacağı oturum ve istenen hizmetin arayüzü.

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

Öncelikle, yeni hesabımızın ayarlarını içeren bir ManagedCustomer nesnesi oluşturacağız. Bu codelab için para birimini ABD doları, saat dilimini ise ABD batı sahiliyle aynı olacak şekilde bir test hesabı oluşturacağı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, hesabın adına ekleyeceğimiz rastgele bir sayı oluştururuz. Bunun nedeni, burada oluşturacağımız AdWords hesabını daha sonra oluşturacağımız Merchant Center hesabıyla eşleştirebilmektir. Böylece, çözümümüz tamamlandığında bunları görsel olarak inceleyebilir ve ikisini gerçekten birbirine bağladığından emin olabiliriz.

Yeni yönetilen hesabı oluşturma

Yeni hesabı gerçekten oluşturmak için ADD işlemini belirtmek üzere ManagedCustomerOperation sınıfını kullanırız:

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 değerlerinin listesini içeren bir değerdir. Burada, oluşturduğumuz yeni hesap olan tek bir müşteriyi içeren bir liste olacaktır. Gelecekte kullanmak üzere bu yeni hesabın kimliğini alırız ve çözümümüzün çıktısı olarak görebilmemiz 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

Önceki 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 yine hata görmezsiniz. Bu kez, oluşturduğumuz yeni AdWords hesabının kimliğini göreceğiz. Yönetici hesabınız için AdWords sitesini kontrol edin. Yeni hesabı burada da göreceksiniz.

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

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

Bu adımda, son adımda oluşturduğumuz AdWords hesabına bağlayacağımız Merchant Center alt hesabını oluşturacağız. İlgili AdWords hesabının kimliğine zaten sahip olduğumuz için, alt hesabı oluşturduktan sonra ayrı olarak bağlantı istemek yerine bağlantıyı oluşturma sırasında isteyebiliriz.

Yeni alt hesabın ayarlarını belirtin

AdWords API'den farklı olarak, Account model sınıfının ayarlayıcıları nesneyi döndürür. Böylece, yeni Account nesnesinde onlara yönelik çağrılarımızı zincirleyebiliriz. AdWords 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 hesap için AdwordsLinks listesine hemen 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ıyoruz ve ardından bir işlem nesnesi oluşturmak yerine doğrudan insert() yöntemini çağırıyoruz. Bu yöntem iki bağımsız değişken alı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üm önemli bir bilgi (yeni alt hesabın kimliği) içerdiğinden orijinal Account nesnemizin üzerine yazarız. Çözümümüzü çalıştırıp yeni alt hesabın Merchant Center'da var olduğunu doğrulayabilmek için bu değeri çözümümüzün çıktısına yazdırırız.

Test edin

Önceki 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 yine hata görmezsiniz. Bu kez hem yeni AdWords hesabının hem de yeni Merchant Center hesabının kimliklerini göreceğiz. Yeni alt hesabı görmek için çok müşterili hesabınızın Merchant Center'ını kontrol edin.

Not: AdWords'de olduğu gibi, çözümün her çalıştırması 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 edin

Son adımda, yeni bir Merchant Center alt hesabı oluşturduk ve aynı zamanda 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şme

Daha önce olduğu gibi, CustomerService için istemci almak üzere AdWordsServices sınıfını kullanacağız. Ancak, müşteriyi oluşturmadan önce AdWords oturum nesnesini değiştiririz. Böylece, gelecekteki kullanımlar yönetici hesabı yerine yeni yönetilen hesapta çalışır. Sonuçta, Merchant Center hesabı yönetici hesabı için değil yönetilen hesap için bağlantı isteğinde bulunmuştur.

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ı belirtin

Yeni bir AdWords hesabı oluştururken yaptığımız 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, SET hesabını ise ACTIVE hesabına taşımak istiyoruz. serviceLinkId ayarı için AdWords'deki hizmet bağlantısının kimliği olarak kullanacağımız için 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. Önceki gibi, bir dizi hizmet bağlantısı işlemi alır. Bu kez yöntem, doğrudan (muhtemelen değiştirilmiş) hizmet bağlantılarının listesini döndürüyor. Bu nedenle, bu listeyi döngü yaparak çö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

Önceki 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örmezsiniz. Bu kez, hizmet bağlantısının etkin olacak şekilde güncellendiğine dair bir not da göreceğiz. AdWords ve Merchant Center'ı kontrol edin ve hesapların gerçekten bağlı olup olmadığını tekrar kontrol edin.

8. Bir temanın varyasyonları

Codelab'i tamamladığınız için tebrikler. Tamamen çalışan bir çözüme sahip olduğunuza göre, bu kod laboratuvarındaki API'lerden 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 kredi: AdWords bağlantısı isteğinde bulunmak için mevcut bir Merchant Center hesabını güncelleme

Codelab'de, Merchant Center hesabını oluştururken bağlantı isteğinde bulunmak için bilgilerini kullanabilmek amacıyla AdWords hesabını akıllıca önce oluşturduk. Ancak Merchant Center hesabı zaten mevcutsa bunun yerine yapılandırmasını güncellemeniz gerekir. Kodunuzu, önce Merchant Center hesabını oluşturacak şekilde değiştirmeyi deneyin. Ardından AdWords hesabını oluşturduktan sonra geri dönüp yapılandırmasını bağlantı isteğinde bulunacak şekilde güncelleyin.

Not: Accounts.update veya Accounts.patch yöntemini kullanmanız gerekir. Hatta farkı anlamak için her bir sürümle birer reklam deneyebilirsiniz.

Önemli: Yeni Merchant Center hesabı, Accounts.insert çağrısından hemen sonra kullanılamayabilir. Yeni hesap kullanıma sunulana kadar, hesaba erişmeye veya hesabı değiştirmeye çalıştığınızda 401 HTTP hatası alırsınız. Alışveriş örneklerinde, AccountWorkflow.java yöntemindeki yöntemleri yeniden denemek için eksponansiyel geri yükleme kullanma örneği bulunur. Bu örnekte, BaseWorkflowSample.java yöntemindeki retryFailures yöntemi kullanılır.

Ek kredi: AdWords ve Merchant Center hesap bilgilerini alarak bağlantı oluşturma işlemini doğrulayın

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

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

Dünya sizin için fırsatlarla dolu

Yapabileceğiniz başka değişiklikler varsa bunları deneyebilirsiniz. Fikirleriniz için referans koda ihtiyacınız varsa Google Alışveriş örneklerini ve Google Ads Java istemci kitaplığı kaynağındaki examples dizinini inceleyin.