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ışmaya ve her ikisini de kullanan bir uygulama oluşturmaya ilişkin bazı temel bilgileri öğreneceksiniz. Özellikle, bir AdWords hesabı ile Merchant Center hesabını oluşturup bağlayacak bir komut satırı uygulaması oluşturmanız gerekir.

Neler öğreneceksiniz?

• Yönetici hesabı tarafından yönetilen AdWords hesapları nasıl oluşturulur?
• Çok müşterili bir hesap tarafından yönetilen Merchant Center hesapları nasıl oluşturulur?
• Merchant Center hesabından AdWords hesabına bağlantı isteğinde bulunma
• Beklemedeki bir Merchant Center bağlantısı AdWords hesabında nasıl kabul edilir?

Gerekenler

• Bir AdWords yönetici hesabı
• Merchant Center çok müşterili hesabı
• Java 7+
• Maven
• Örnek kod
• Metin düzenleyici (Eclipse veya IntelliJ gibi Maven projelerini anlayan bir entegre geliştirme ortamı önerilir)

2. Kurulum

Kodu indir

Bu codelab'e ait tüm kodları indirmek için şu bağlantıyı tıklayın:

Kaynak kodu indir

İndirilen zip dosyasının paketini açın. Bu işlem, ihtiyacınız olan tüm kaynakların yanı sıra bir Maven projesi içeren kök klasörün (shopping-account-linking-master) paketini açar. Aşağıdaki alt dizinler özellikle önemlidir:

• 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çeriyor.

Gerekli paketleri ve derlemeyi yükleme

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

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

mvn compile

3. Kimlik doğrulamayı ayarlayın

Bu adımda herhangi bir kodlama yapmayacağız. Bunun yerine, AdWords API ve Content API for Shopping için uygun kimlik doğrulama jetonlarını içeren dosyalar oluşturacağız.

AdWords API kimliğini ayarlama

Bu codelab'de, istemci kitaplığıyla aynı kimlik bilgisi yükleme işlemi kullanılmaktadır. Bu nedenle, yönetici hesabınızla Java için Google Ads API'leri İstemci Kitaplığı'nı daha önce kullandıysanız ayarlama yapılmış olması gerekir. Aksi halde, Java için Google Ads API'leri İstemci Kitaplığı'nı kullanmaya başlamak üzere 1-3 arasındaki adımları uygulayın.

Content API kimliğini ayarlama

Hizmet hesabı anahtarınız yoksa:

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

Şimdi, bir hizmet hesabıyla Alışveriş örnekleri için kimlik doğrulama ayarlama talimatlarını uygulayın. Yani hizmet hesabı anahtarınızın bir kopyası, ana dizininizden şu yolda olmalı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

Artık kimlik doğrulama jetonlarınız doğru yerlerde olduğuna göre örnekleri çalıştırmayı deneyebilirsiniz. Komut satırında Maven'i kullanıyorsanız aşağıdaki komutları çalıştırın:

mvn compile

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

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

Sağlanmayan oturum nesnelerinin sağlandığı ile ilgili bir hata mesajı alırsanız kimlik doğrulama jetonlarınız doğru yerdedir ve düzgün çalışıyordur! Aksi takdirde, aldığınız hata mesajı hangi kimlik bilgilerinin çalışmadığını ve hangi dosyayı düzeltmeniz gerektiğini size 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 özellikle çok müşterili hesabınıza yönelik bir hizmet hesabı anahtarı almak için yukarıdaki adımları uygulayın.

4. API'lere bağlanın

Kullanacağımız iki API için geçerli kimlik doğrulama jetonlarına sahip olduğunuza göre şimdi gerçek kodu doldurmaya başlayalım. Kimlik doğrulama jetonlarımızı kullanarak oturum nesneleri oluşturarak başlayacağız. Sonraki adımlarda, her bir API'nin bu oturum nesnelerini kullanarak sağladığı ç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şturacağız ve bu nesneyi kullanarak uygun ShoppingContent nesnesini oluşturacağız. Neyse ki ilkini oluşturmak için gereken tek şey kod iskeletinde zaten mevcuttur. Bu nedenle, aşağıdaki şekilde bir araya getirmemiz gerekir:

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 aşağıdaki kod örneklerindeki ilk yorumlar kod iskeletinde zaten mevcut. Bu satırların nereye eklenmesi gerektiğini görmek için bu öğeleri arayın.

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

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

AdWords API oturumu nesnesi oluşturma

Benzer şekilde, AdWordsSession nesneleri oluşturmak için bir AdWordsSession.Builder sınıfı bulunur. Buradaki temel fark, yapılandırma seçeneklerini doğrudan oluşturucu üzerinde ayarlamak yerine, önceki adımda oluşturduğumuz ads.properties dosyasından yüklemek için fromFile() yöntemini kullanmamı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 derleyip çalıştırmak için (komut satırından çalıştırıyorsanız) son bölümdeki komutların aynısını kullanacağız:

mvn compile

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

Bu kez, herhangi bir hata almazsınız ancak ilginç bir sonuç da almazsınız. Yeni hesapları oluşturmak ve bağlamak için API'leri çağırdığımızda bunu ekleriz.

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

Artık API oturumu nesnelerimizi oluşturduğumuza göre adım adım ilerleyip bağlamak istediğimiz hesapları oluşturacağız. AdWords'le başlayalım ve yönetici hesabımız altında bir test hesabı oluşturacağız.

Not: Bu bölümdeki tüm kod snippet'leri, iskelet kodda aynı yere verildikleri sırayla eklenir. Bu nedenle, yalnızca yorumu (ilk yorumda yerleştirileceği yeri işaretleyen // TODO...)) gösteririz. Dolayısıyla, bu ve sonraki adımlarda, giriş yorumu içermeyen kod snippet'leri görürseniz bunlar önceki snippet'in hemen ardından gelir.

ManagedCustomerService'e erişme

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

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, AdWords "müşterilerini" yönetmemize olanak tanıyan ManagedCustomerService bölümüne erişiriz (hesaplar).

Yeni hesap ayarlarını belirleme

İlk olarak, yeni hesabımızın ayarlarını içeren bir ManagedCustomer nesnesi oluşturacağız. Bu codelab için, para birimini ABD doları, saat dilimi ABD batı yakası ile 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, hesap adına eklediğimiz rastgele bir sayı da oluştururuz. Bu sayede, burada oluşturacağımız AdWords hesabını, daha sonra oluşturacağımız Merchant Center hesabıyla eşleştirebiliriz. Böylece, çözümümüz tamamlandıktan sonra bu hesapları görsel olarak inceleyebilir ve hesabın gerçekten bu ikisi arasında bağlantı oluşturduğundan emin olabiliriz.

Yeni yönetilen hesabı oluşturma

Yeni hesabı oluşturmak için ManagedCustomerOperation'ı kullanarak bir ADD işlemi belirtiriz:

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ştireceğiz. Bu yöntemin gerçekleştirilmesi için bir dizi işlem gerekir ancak burada yalnızca tek bir işlem gerçekleştirmek istiyoruz. mutate() yönteminin sonucu, ManagedCustomer listesi içeren bir değerdir; burada bir müşteri, oluşturduğumuz yeni hesabı içeren bir liste olacaktır. Bu yeni hesabın kimliğini ileride 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. Komut satırından Maven kullanıyorsanız:

mvn compile

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

Her şey yolunda giderse hiçbir hata görmezsiniz. 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 da burada listelendiğini göreceksiniz.

Not: Bu noktada, çözümün her çalıştırılması yeni hesaplar oluşturur. Çözümünüzü tamamladıktan sonra, oluşturulan tüm AdWords hesaplarını AdWords sitesi üzerinden iptal edebilirsiniz. Sonuçta, bu hesaplar için adlandırma planımız, 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. Alt hesabı oluşturduktan sonra ayrı olarak bağlantı istemek yerine, ilgili AdWords hesabının kimliğine zaten sahip olduğumuzdan bağlantı isteğinde bulunabiliriz.

Yeni alt hesabın ayarlarını belirleme

AdWords API'den farklı olarak, Account model sınıfının belirleyicileri nesneyi döndürür. Böylece, çağrılarımızı yeni Account nesnesinde onlara zincirleyebiliriz. AdWords hesabını oluştururken 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ği zaten elimizde olduğundan, bu kimliği artık yeni alt hesap için 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şturma

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öntem iki bağımsız değişken alır: altında 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, yeni alt hesabın kimliği gibi önemli bir bilgi içerdiği için orijinal Account nesnemizin üzerine yazılır. Bunu çözümümüzdeki çıktıda yazdırırız. Böylece çözümümüzü çalıştırabilir ve 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. Komut satırından Maven kullanıyorsanız:

mvn compile

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

Her şey yolunda giderse herhangi bir hata görmezsiniz. Bu kez hem yeni AdWords hesabının hem de yeni Merchant Center hesabının kimlikleri görünür. Yeni alt hesabı görmek için çok müşterili hesabınızın Merchant Center sayfasına göz atın.

Not: AdWords'de olduğu gibi, çözümün her çalışması artık yeni Merchant Center hesapları oluşturur. Çözümünüzü tamamladıktan sonra, oluşturulan alt hesapları Merchant Center aracılığıyla silebilirsiniz.

7. Bağlantıyı AdWords hesabından kabul edin

Son adımda yeni bir Merchant Center alt hesabı oluşturduk ve yeni AdWords hesabımızın bağlantısını aynı anda istiyorduk. Bu adımda, istenen bağlantıyı kabul etmek için AdWords API'yi kullanarak işlemi tamamlayacağız.

CustomerService hizmetine erişme

Daha önce olduğu gibi CustomerService için bir müşteri bulmak amacıyla AdWordsServices sınıfını kullanacağız. Ancak, müşteriyi oluşturmadan önce, ilk olarak AdWords oturumu nesnemizi 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ı 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 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, beklemedeki hizmet bağlantısını bir MERCHANT_CENTER hesabına, SET bağlantısını da ACTIVE hesabına aktarmak istiyoruz. serviceLinkId ayarı için yeni oluşturduğumuz Merchant Center hesabının kimliğini kullanacağız. Bu kimlik, AdWords'deki hizmet bağlantısının kimliği için kullanılmaktadır.

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 et

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 doğrudan hizmet bağlantılarının bir listesini (muhtemelen değiştirilmiş) döndürür; böylece çözümümüzün sonucunu bu listenin sonucuna döndürerek yazdırırız. Elbette, yalnızca tek bir işlem belirttiğimiz için çıkışta yalnızca tek bir bağlantı 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. Komut satırından Maven kullanıyorsanız:

mvn compile

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

Her şey yolunda giderse herhangi bir hata görmezsiniz. Bu kez ayrıca hizmet bağlantısının etkin olacak şekilde güncellendiğine dair bir not da gösterilir. AdWords ve Merchant Center'ı kontrol edin ve hesapların bağlı olup olmadığını bir kez daha kontrol edin.

8. Temadaki farklılıklar

Tebrikler, codelab'i tamamladınız. Artık tam olarak çalışan bir çözümünüz olduğuna göre bu codelab'de gördüğünüz daha fazla API'yi kullanmak için çözümü nasıl değiştirebileceğinize veya genişletebileceğinize dair bazı örneklere bakalım.

Ek kredi: AdWords bağlantısı istemek için mevcut Merchant Center hesabını güncelleyin

Codelab'de, Merchant Center hesabını oluştururken bağlantı isteğinde bulunmak için hesap bilgilerini kullanmak amacıyla öncelikle AdWords hesabını oluşturduk. Ancak Merchant Center hesabı zaten mevcutsa 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ıyı istemek için hesabın yapılandırmasını güncelleyin.

Not: Accounts.update veya Accounts.patch yöntemini kullanmanız gerekir. Aslında farkı anlamak için her biri için ayrı bir sürüm deneyin.

Önemli: Accounts.insert ile yapılan çağrıdan hemen sonra yeni bir Merchant Center hesabı kullanılamayabilir. Yeni hesap kullanılabilir hale gelene kadar, hesaba erişme veya hesabı değiştirme girişimlerinde 401 HTTP hatası alırsınız. Alışveriş örneklerinde, AccountWorkflow.java'te yöntemleri yeniden denemek için eksponansiyel geri yüklemenin kullanılmasına dair bir örnek bulunmaktadır. Bu yöntemde BaseWorkflowSample.java'deki 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ını başarının bir işareti 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 bakabilirsiniz. AdWords tarafında, CustomerServiceInterface nesnesinin getServiceLinks yöntemini kullanmanız gerekir.

Bu dünya sizi bekliyor

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