Üçüncü Taraf API'ler

Google Ads komut dosyalarının güçlü bir özelliği, üçüncü taraf API'lerinden gelen veriler ve hizmetlerle entegre olabilmesidir.

Bu kılavuzda, diğer hizmetlere bağlanmak için komut dosyaları yazmanıza yardımcı olabilecek aşağıdaki kavramlar ele alınmaktadır:

  • HTTP istekleri gönderme: Harici API'lere erişmek için UrlFetchApp hizmetini kullanma
  • Kimlik doğrulama: Sık karşılaşılan bazı kimlik doğrulama senaryolarını ele alıyoruz.
  • Yanıtları ayrıştırma: Döndürülen JSON ve XML verilerinin nasıl işleneceği.

Ayrıca bu kavramları gösteren bir dizi popüler API için örnekler de ekledik.

UrlFetchApp ile veri getirme

UrlFetchApp, üçüncü taraf API'lerle etkileşim kurmak için gereken temel işlevleri sağlar.

Aşağıdaki örnekte, OpenWeatherMap'ten hava durumu verilerinin alınması gösterilmektedir. Nispeten basit yetkilendirme şeması ve API'si nedeniyle OpenWeatherMap'i seçtik.

İstekte bulunun

OpenWeatherMap dokümanlarında, mevcut hava durumunu öğrenmek için gönderilecek isteğin biçimi şu şekilde belirtilmiştir:

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

URL, ilk yetkilendirme örneğimizi sağlar: apikey parametresi gereklidir ve değer her kullanıcı için benzersizdir. Bu anahtar, kaydolarak alınır.

Kaydolduktan sonra anahtarı kullanarak aşağıdaki gibi bir istek gönderebilirsiniz:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

Bu kodun yürütülmesi, Google Ads komut dosyalarındaki günlük kaydı penceresine yazılan uzun bir JSON metin dizesiyle sonuçlanır.

Bir sonraki adım, bunu komut dosyanızda kullanılabilecek bir biçime dönüştürmektir.

JSON verileri

Birçok API, JSON biçiminde yanıt verir. Bu, JavaScript nesnelerinin serileştirilmesini temsil eder. Böylece nesneler, diziler ve temel türler dize olarak temsil edilip aktarılabilir.

OpenWeatherMap'ten döndürülen dize gibi bir JSON dizesini tekrar JavaScript nesnesine dönüştürmek için yerleşik JSON.parse yöntemini kullanın. Önceki örnekten devam edelim:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

JSON.parse yöntemi, dizeyi name özelliğine sahip bir nesneye dönüştürür.

Farklı biçimlerdeki API yanıtlarıyla çalışma hakkında daha fazla bilgi için Yanıtları ayrıştırma bölümüne bakın.

Hata işleme

Üçüncü taraf API'leri sık sık değiştiğinden ve beklenmeyen yanıt değerleri oluşturduğundan, komut dosyalarınızda üçüncü taraf API'leriyle çalışırken hata işleme önemli bir konudur. Örneğin:

  • API'nin URL'si veya parametreleri bilginiz dışında değişebilir.
  • API anahtarınızın (veya diğer kullanıcı kimlik bilgilerinizin) süresi dolabilir.
  • Yanıtın biçimi önceden haber verilmeksizin değiştirilebilir.

HTTP durum kodları

Beklenmeyen yanıtlar olabileceğinden HTTP durum kodunu incelemeniz gerekir. Varsayılan olarak, bir HTTP hata koduyla karşılaşılırsa UrlFetchApp bir istisna oluşturur. Bu davranışı değiştirmek için aşağıdaki örnekte olduğu gibi isteğe bağlı bir parametre iletmek gerekir:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

Yanıt yapısı

Üçüncü taraf API'leri değiştiğinde, komut dosyalarınızı etkileyebilecek değişikliklerden hemen haberdar olmayabilirsiniz. Örneğin, OpenWeatherMap örneğinde döndürülen name özelliği locationName olarak değiştirilirse bu özelliği kullanan komut dosyaları başarısız olur.

Bu nedenle, döndürülen yapının beklendiği gibi olup olmadığını test etmek faydalı olabilir. Örneğin:

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

UrlFetchApp ile POST verileri gönderme

OpenWeatherMap ile ilgili giriş örneğinde yalnızca veri getirilmişti. Genellikle, uzak sunucuda durumu değiştirmeyen API çağrıları HTTP GET yöntemini kullanır.

GET yöntemi, UrlFetchApp için varsayılan yöntemdir. Ancak SMS mesajları gönderen bir hizmete yapılan çağrılar gibi bazı API çağrıları için POST veya PUT gibi başka yöntemler gerekir.

POST çağrılarının UrlFetchApp ile kullanımını göstermek için aşağıdaki örnekte, Slack kullanıcılarına ve gruplarına Slack mesajı göndermek üzere ortak çalışma mesajlaşma uygulaması Slack ile entegrasyon gösterilmektedir.

Slack'i kurun

Bu kılavuzda, Slack hesabına zaten kaydolduğunuz varsayılmaktadır.

Önceki örnekteki OpenWeatherMap'te olduğu gibi, mesaj göndermeyi etkinleştirmek için bir jeton almak gerekir. Slack, ekibinize mesaj göndermenize olanak tanıyan benzersiz bir URL sağlar. Bu URL'ye Gelen Webhook adı verilir.

Add Incoming WebHooks Integration'ı (Gelen Webhook Entegrasyonu Ekle) tıklayıp talimatları uygulayarak gelen webhook ayarlayın. İşlem, mesajlaşma için kullanılacak bir URL oluşturmalıdır.

POST isteği gönderme

Gelen Webhook'unuzu ayarladıktan sonra POST isteği göndermek için UrlFetchApp.fetch'ye iletilen options parametresinde bazı ek özelliklerin kullanılması gerekir:

  • method: Belirtildiği gibi, bu varsayılan olarak GET değerine ayarlanır ancak burada bu değeri geçersiz kılıp POST olarak ayarlıyoruz.
  • payload: Bu, POST isteğinin bir parçası olarak sunucuya gönderilecek verilerdir. Bu örnekte Slack, Slack belgelerinde açıklandığı gibi JSON biçiminde serileştirilmiş bir nesne bekler. Bunun için [JSON.stringify][json-stringify-url] yöntemi kullanılır ve Content-Type, application/json olarak ayarlanır.

      // Change the URL for the one issued to you from 'Setting up Slack'.
      const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
      const slackMessage = {
        text: 'Hello, slack!'
      };
    
      const options = {
        method: 'POST',
        contentType: 'application/json',
        payload: JSON.stringify(slackMessage)
      };
      UrlFetchApp.fetch(SLACK_URL, options);
    

Genişletilmiş Slack örneği

Önceki örnekte, Slack'e gelen mesajları etkinleştirmek için gereken minimum kod gösterilmektedir. Kapsamlı bir örnek, bir gruba Kampanya Performans Raporu oluşturulup gönderilmesini ve bazı biçimlendirme ve görüntüleme seçeneklerini gösterir.

Gelen mesaj

Slack mesajları hakkında daha fazla bilgi için Slack belgelerindeki mesaj biçimlendirme bölümüne bakın.

Form verileri

Önceki örnekte, POST isteği için payload özelliği olarak bir JSON dizesinin kullanımı gösterilmiştir.

payload biçimine bağlı olarak UrlFetchApp, POST isteğini oluşturmak için farklı yaklaşımlar kullanır:

  • payload bir dize olduğunda dize bağımsız değişkeni, isteğin gövdesi olarak gönderilir.
  • payload bir nesne olduğunda (ör. değerlerin eşlemesi):

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
    

    Anahtar/değer çiftleri form verilerine dönüştürülür:

    subject=Test&to=mail@example.com&body=Hello,+World!
    

    Ayrıca, isteğin Content-Type başlığı application/x-www-form-urlencoded olarak ayarlanır.

Bazı API'ler, POST istekleri gönderilirken form verilerinin kullanılmasını gerektirir. Bu nedenle, JavaScript nesnelerinin form verilerine otomatik olarak dönüştürülmesini göz önünde bulundurmanız faydalı olacaktır.

HTTP temel kimlik doğrulaması

HTTP temel kimlik doğrulaması, en basit kimlik doğrulama biçimlerinden biridir ve birçok API tarafından kullanılır.

Kimlik doğrulama, her istekteki HTTP üstbilgilerine kodlanmış bir kullanıcı adı ve şifre eklenerek gerçekleştirilir.

HTTP temel kimlik doğrulaması

İstek oluşturma

Kimliği doğrulanmış bir istek oluşturmak için aşağıdaki adımlar gereklidir:

  1. Kullanıcı adı ve şifreyi iki nokta üst üste işaretiyle birleştirerek parolayı oluşturun (ör. username:password).
  2. Parolayı Base64 olarak kodlayın. Örneğin, username:password, dXNlcm5hbWU6cGFzc3dvcmQ= olur.
  3. İsteğe Authorization: Basic <encoded passphrase> biçiminde bir Authorization üstbilgisi ekleyin.

Aşağıdaki snippet, Google Ads komut dosyalarında bunun nasıl yapılacağını göstermektedir:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

Temel kimlik doğrulama örnekleri

Kod örnekleri bölümünde, HTTP Temel Kimlik Doğrulaması'nın kullanımını gösteren iki örnek yer alır:

Plivo

Plivo, API'si ile SMS mesajlarının gönderilmesini ve alınmasını kolaylaştıran bir hizmettir. Bu örnekte mesaj gönderme işlemi gösterilmektedir.

  1. Plivo'ya kaydolun.
  2. Örnek komut dosyasını Google Ads'deki yeni bir komut dosyasına yapıştırın.
  3. PLIVO_ACCOUNT_AUTHID ve PLIVO_ACCOUNT_AUTHTOKEN değerlerini yönetim kontrol panelindeki değerlerle değiştirin.
  4. Hataların bildirilmesi için komut dosyasında belirtilen e-posta adresinizi girin.
  5. Plivo'yu kullanmak için numara satın almanız veya deneme hesabına numara eklemeniz gerekir. Deneme hesabıyla kullanılabilecek Sandbox numaraları ekleyin.
  6. Hem gönderen olarak görünecek numarayı hem de alıcı numarasını ekleyin.
  7. Komut dosyasındaki PLIVO_SRC_PHONE_NUMBER değerini, yeni kaydedilen korumalı alan numaralarından biriyle güncelleyin. Bu numara, uluslararası ülke kodunu içermelidir. Örneğin, Birleşik Krallık numarası için 447777123456.

Twilio

Twilio, API'si ile SMS mesajlarının gönderilmesini ve alınmasını kolaylaştıran başka bir hizmettir. Bu örnekte mesaj gönderme işlemi gösterilmektedir.

  1. Twillio'ya kaydolun.
  2. Örnek komut dosyasını Google Ads'deki yeni bir komut dosyasına yapıştırın.
  3. TWILIO_ACCOUNT_SID ve TWILIO_ACCOUNT_AUTHTOKEN değerlerini hesap konsolu sayfasında gösterilen değerlerle değiştirin.
  4. TWILIO_SRC_PHONE_NUMBER ifadesini kontrol panelindeki numarayla değiştirin. Bu, Twilio tarafından mesaj göndermek için yetkilendirilen numaradır.

OAuth 1.0

Birçok popüler hizmet, kimlik doğrulama için OAuth'u kullanır. OAuth'un çeşitli türleri ve sürümleri vardır.

HTTP temel kimlik doğrulamasında kullanıcının yalnızca bir kullanıcı adı ve şifresi varken OAuth, üçüncü taraf uygulamalarına, o üçüncü taraf uygulamasına özgü kimlik bilgilerini kullanarak kullanıcının hesabına ve verilerine erişim izni verilmesini sağlar. Ayrıca, erişimin kapsamı da söz konusu uygulamaya özel olacaktır.

OAuth 1.0 hakkında bilgi edinmek için OAuth Core kılavuzuna bakın. Özellikle 6. OAuth ile kimlik doğrulama. Tam üç aşamalı OAuth 1.0'da süreç şu şekildedir:

  1. Uygulama ("Tüketici") bir istek jetonu alır.
  2. Kullanıcı, istek jetonunu yetkilendirir.
  3. Uygulama, istek jetonunu bir erişim jetonuyla değiştirir.
  4. Sonraki tüm kaynak istekleri için erişim jetonu, imzalı bir istekte kullanılır.

Üçüncü taraf hizmetlerinin OAuth 1.0'ı kullanıcı etkileşimi olmadan kullanması için (ör. Google Ads komut dosyalarının gerektirdiği şekilde) 1, 2 ve 3. adımlar mümkün değildir. Bu nedenle, bazı hizmetler yapılandırma konsollarından bir erişim jetonu yayınlayarak uygulamanın doğrudan 4. adıma geçmesine olanak tanır. Bu, tek bacaklı OAuth 1.0 olarak bilinir.

OAuth1

Google Ads komut dosyalarında OAuth 1.0

Google Ads komut dosyaları için her komut dosyası genellikle bir uygulama olarak yorumlanır. Hizmetin konsolu veya yönetim ayarları sayfası üzerinden genellikle şunları yapmanız gerekir:

  • Komut dosyasını temsil edecek bir uygulama yapılandırması oluşturun.
  • Komut dosyasına hangi izinlerin verildiğini belirtin.
  • Tek aşamalı OAuth ile kullanmak için tüketici anahtarı, tüketici gizli anahtarı, erişim jetonu ve erişim gizli anahtarı alın.

OAuth 2.0

OAuth 2.0, kullanıcı verilerine erişim sağlamak için popüler API'lerde kullanılır. Belirli bir üçüncü taraf hizmetine ait hesabın sahibi, belirli uygulamalara kullanıcı verilerine erişim izni verir. Bu yaklaşımın avantajları şunlardır:

  • Hesap kimlik bilgilerini uygulamayla paylaşması gerekmez.
  • Hangi uygulamaların verilere ayrı ayrı erişebileceğini ve ne ölçüde erişebileceğini kontrol edebilir. (Örneğin, verilen erişim salt okuma olabilir veya yalnızca verilerin bir alt kümesine erişim verilebilir.)

Google Ads komut dosyalarında OAuth 2.0 özellikli hizmetleri kullanmak için birkaç adım vardır:

Komut dosyanızın dışında

Google Ads komut dosyalarının, üçüncü taraf API'si aracılığıyla kullanıcı verilerinize erişmesine izin verin. Çoğu durumda bu, üçüncü taraf hizmetinin konsolunda bir uygulama oluşturmayı gerektirir. Bu uygulama, komut dosyanızı temsil eder.

Google Ads komut dosyaları uygulamasına hangi erişim haklarının verilmesi gerektiğini belirtirsiniz. Genellikle uygulamaya bir istemci kimliği atanır. Bu sayede, OAuth 2.0 aracılığıyla üçüncü taraf hizmetindeki verilerinize hangi uygulamaların erişebileceğini ve bu verilerin hangi kısımlarını görebileceğini veya değiştirebileceğini kontrol edebilirsiniz.

Senaryonuzda

Uzak sunucuyla yetkilendirme yapın. Sunucunun izin verdiği yetkilendirme türüne bağlı olarak, akış olarak bilinen farklı bir adım dizisinin izlenmesi gerekir. Ancak tüm akışlar, ilgili oturumda sonraki tüm istekler için kullanılacak bir erişim jetonunun verilmesiyle sonuçlanır.

API istekleri gönderme Her istekle birlikte erişim jetonunu iletin.

Yetkilendirme akışları

Her yetkilendirme türü ve ilgili akış, farklı kullanım senaryolarına uygundur. Örneğin, kullanıcının etkileşimli bir oturuma katıldığı durumlarda, uygulamanın kullanıcı olmadan arka planda çalışması gereken senaryoya kıyasla farklı bir akış kullanılır.

API sağlayıcılar, kabul ettikleri yetkilendirme türlerine karar verir ve bu da kullanıcının API'sini entegre etme sürecine rehberlik eder.

Uygulama

Tüm farklı OAuth akışlarında amaç, oturumun geri kalanında isteklerin kimliğini doğrulamak için kullanılabilecek bir erişim jetonu elde etmektir.

Örnek kitaplık, her farklı akış türü için kimlik doğrulamanın nasıl yapılacağını gösterir. Bu yöntemlerin her biri, erişim jetonunu alıp depolayan ve kimliği doğrulanmış istekleri kolaylaştıran bir nesne döndürür.

Genel kullanım kalıbı şöyledir:

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

İstemci kimlik bilgileri izni

[İstemci kimlik bilgileri verme][client-credentials-rfc], OAuth2 akışının daha basit biçimlerinden biridir. Bu akışta uygulama, sınırlı süreli bir erişim jetonu karşılığında uygulamaya özgü bir kimlik ve gizli anahtar paylaşır.

İstemci kimlik bilgisi

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

Yenileme jetonu izni

Yenileme jetonu izni, istemci kimlik bilgileri iznine benzer. Sunucuya gönderilen istek, oturumda kullanılabilecek bir erişim jetonu döndürür.

Yenileme jetonu

Yenileme jetonu alma

Yenileme jetonu izniyle arasındaki fark, istemci kimlik bilgileri izni için gereken ayrıntıların uygulama yapılandırmasından (ör. hizmetin denetim masasında) gelmesi, yenileme jetonunun ise kullanıcı etkileşimi gerektiren [yetkilendirme kodu izni][authorization-code-rfc] gibi daha karmaşık bir akışın parçası olarak verilmesidir:

Yetkilendirme kodu

Yenileme jetonu almak için OAuth Playground'u kullanma

OAuth2 Playground, kullanıcının yenileme jetonu almak için yetkilendirme kodu izni adımlarını uygulayabileceği bir kullanıcı arayüzü sağlar.

Sağ üstteki ayarlar düğmesi, OAuth akışında kullanılacak tüm parametreleri tanımlamanıza olanak tanır. Bu parametreler şunlardır:

  • Yetkilendirme uç noktası: Yetkilendirme akışının başlangıcı olarak kullanılır.
  • Jeton uç noktası: Erişim jetonu almak için yenileme jetonu ile birlikte kullanılır.
  • İstemci kimliği ve gizli anahtarı: Uygulamanın kimlik bilgileri.

    OAuth Playground

Yenileme jetonu kullanımı

İlk yetkilendirme gerçekleştirildikten sonra hizmetler, istemci kimlik bilgileri akışına benzer şekilde kullanılabilecek bir yenileme jetonu verebilir:

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

Search Ads 360 örneği

Search Ads 360, yenileme jetonuyla kullanılabilen bir API örneğidir. Bu örnekte, bir komut dosyası rapor oluşturur ve döndürür. Gerçekleştirilebilecek diğer işlemlerle ilgili tüm ayrıntılar için Search Ads 360 API referansına bakın.

Komut dosyasını oluşturma
  1. Google Cloud Console'da yeni bir proje oluşturun ve Search Ads 360 kılavuzundaki prosedürü uygulayarak istemci kimliği, istemci gizli anahtarı ve yenileme jetonu alın. Search Ads 360 API'yi etkinleştirdiğinizden emin olun.
  2. [Örnek komut dosyasını][search-ads-360-example] Google Ads'deki yeni bir komut dosyasına yapıştırın.
  3. [Örnek OAuth2 kitaplığını][oauth20-library-example] kod listesinin altına yapıştırın.
  4. Komut dosyasını istemci kimliği, istemci gizli anahtarı ve yenileme jetonu için doğru değerleri içerecek şekilde değiştirin.

Apps Komut Dosyası Execution API örneği

Bu örnekte, Apps Script Execution API kullanılarak Apps Komut Dosyası'nda bir işlevin nasıl yürütüleceği gösterilmektedir. Bu sayede Google Ads komut dosyalarından Apps Komut Dosyası'nı çağırabilirsiniz.

Apps Komut Dosyası oluşturma

Yeni bir komut dosyası oluşturun. Aşağıdaki örnekte Drive'dan 10 dosya listelenmektedir:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Apps Komut Dosyası'nı yürütme için yapılandırma
  1. Komut dosyasını kaydedin.
  2. Kaynaklar > Cloud Platform projesi'ni tıklayın.
  3. Google Cloud Console'a gitmek için proje adını tıklayın.
  4. API'ler ve Hizmetler'e gidin.
  5. Uygun API'leri etkinleştirin. Bu örnekte Drive API ve Apps Script Execution API'yi etkinleştirmeniz gerekir.
  6. Menüdeki Kimlik bilgileri öğesinden OAuth kimlik bilgileri oluşturun.
  7. Komut dosyanıza geri dönün ve Publish > Deploy as API Executable (Yayınla > API Yürütülebilir Dosyası Olarak Dağıt) seçeneğini kullanarak komut dosyasını yürütülmek üzere yayınlayın.
Google Ads komut dosyasını oluşturma
  1. Örnek komut dosyasını Google Ads'deki yeni bir komut dosyasına yapıştırın.
  2. Ayrıca, kod listesinin altına [örnek OAuth2 kitaplığını][oauth20-library-example] yapıştırın.
  3. Komut dosyasını istemci kimliği, istemci gizli anahtarı ve yenileme jetonu için doğru değerleri içerecek şekilde değiştirin.

Hizmet hesapları

Yetkilendirme türlerine alternatif olarak hizmet hesapları kavramı kullanılır.

Hizmet hesapları, kullanıcı verilerine erişmek için kullanılmadıkları için yetkilendirme türlerinden farklıdır: Kimlik doğrulamanın ardından istekler, projenin sahibi olabilecek kullanıcı olarak değil, uygulama adına hizmet hesabı tarafından yapılır. Örneğin, hizmet hesabı bir dosya oluşturmak için Drive API'yi kullanırsa bu dosya hizmet hesabına ait olur ve varsayılan olarak projenin sahibi tarafından erişilemez.

Google Natural Language API örneği

[Natural Language API][natural-language-api-docs], metin için [duygu analizi][sentiment-analysis-api-docs] ve [varlık analizi][entity-analysis-api-docs] sağlar.

Bu örnekte, başlık veya açıklama dahil olmak üzere reklam metninin [duygu][sentiment-api-docs] değerinin nasıl hesaplanacağı gösterilmektedir. Bu, mesajın ne kadar olumlu olduğunu ve mesajın büyüklüğünü ölçer: Pasta satıyoruz mı yoksa Londra'daki en iyi pastaları satıyoruz mu daha iyi? Hemen satın alın.

Komut dosyasını ayarlama
  1. Google Cloud Console'da yeni bir proje oluşturun.
  2. [Natural Language API][natural-language-api]'yi etkinleştirin.
  3. Proje için faturalandırmayı etkinleştirin.
  4. [Hizmet hesabı oluşturun][create-service-account]. Kimlik bilgileri JSON dosyasını indirin.
  5. [Örnek komut dosyasını][natural-language-example] Google Ads'deki yeni bir komut dosyasına yapıştırın.
  6. Ayrıca, kod listesinin altına [örnek OAuth2 kitaplığını][oauth20-library-example] yapıştırın.
  7. Gerekli değerleri değiştirin:
    • serviceAccount: Hizmet hesabının e-posta adresi (ör. xxxxx@yyyy.iam.gserviceaccount.com).
    • key: Hizmet hesabı oluşturulurken indirilen JSON dosyasındaki anahtar. -----BEGIN PRIVATE KEY... tarihinde başlayıp ...END PRIVATE KEY-----\n tarihinde sona erer.

API yanıtları

API'ler, verileri çeşitli biçimlerde döndürebilir. Bunların en dikkat çekenleri XML ve JSON'dur.

JSON

Yanıt biçimi olarak JSON ile çalışmak genellikle XML'e kıyasla daha kolaydır. Ancak yine de bazı sorunlar ortaya çıkabilir.

Yanıt doğrulama

API çağrısından başarılı bir yanıt aldıktan sonraki adım genellikle JSON dizesini JavaScript nesnesine dönüştürmek için JSON.parse işlevini kullanmaktır. Bu noktada, ayrıştırma işleminin başarısız olduğu durumu ele almak mantıklıdır:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

Ayrıca, API sizin kontrolünüzde değilse yanıtın yapısının değişebileceğini ve özelliklerin artık mevcut olmayabileceğini göz önünde bulundurun:

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

XmlService, komut dosyalarınızın XML yanıt gövdelerindeki verileri ayrıştırmasına ve ayıklamasına olanak tanır.

Doğrulama

XML, API oluşturmak için hâlâ popüler bir biçimdir. API çağrısından gelen yanıt, XmlService parse yöntemi kullanılarak ayrıştırılabilir:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

XmlService.parse, XML'deki hataları algılayıp buna göre istisnalar oluştursa da XML'i bir şemaya göre doğrulama olanağı sunmaz.

Kök öğe

XML dokümanı başarıyla ayrıştırıldıktan sonra kök öğe, getRootElement() yöntemi kullanılarak elde edilir:

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

Ad alanları

Aşağıdaki örnekte, seçilen maçların futbol sonuçlarını almak için Sportradar API kullanılmıştır. XML yanıtı aşağıdaki biçimdedir:

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

Ad alanının kök öğede nasıl belirtildiğine dikkat edin. Bu nedenle, şunları yapmanız gerekir:

  • Ad alanı özelliğini dokümandan ayıklayın.
  • Alt öğeleri gezerken ve bunlara erişirken bu ad alanını kullanın.

Aşağıdaki örnekte, <schedule> öğesine nasıl erişileceği ve önceki doküman snippet'inde <sport_event> alt öğelerinin nasıl aranacağı gösterilmektedir:

const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);

Değerleri alma

Futbol programından alınan örnek şöyle olduğunda:

<sport_event_status status="..." ... />

Özellikler alınabilir. Örneğin:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

Bir öğenin içindeki metin getText() kullanılarak okunabilir ancak bir öğenin birden fazla alt metni varsa bunlar birleştirilir. Birden fazla alt metin öğesinin olabileceği durumlarda getChildren() kullanmayı ve her alt öğe üzerinde iterasyon yapmayı deneyin.

Sportradar örneği

Bu tam Sportradar örneği, futbol maçlarının (özellikle İngiltere Premier Ligi maçlarının) ayrıntılarının nasıl alınacağını gösterir. Soccer API, Sportradar tarafından sunulan çok sayıda spor feed'inden biridir.

Sportradar hesabı oluşturma
  1. Sportradar geliştirici sitesine gidin.
  2. Deneme hesabı için kaydolun.
  3. Kayıt olduktan sonra hesabınızda oturum açın.
  4. Giriş yaptıktan sonra Hesabım'a gidin.

Sportradar, farklı sporları farklı API'lere ayırır. Örneğin, Futbol API'sine erişim satın alabilir ancak Tenis API'sine erişim satın almayabilirsiniz. Oluşturduğunuz her uygulamanın farklı spor dalları ve farklı anahtarları olabilir.

  1. Applications (Uygulamalar) bölümünde Create a new Application'ı (Yeni uygulama oluştur) tıklayın. Uygulamaya bir ad ve açıklama verin, web sitesi alanını ise yoksayın.
  2. Yalnızca Soccer Trial Europe v2 için yeni bir anahtar ver'i seçin.
  3. Register Application'ı (Uygulamayı Kaydet) tıklayın.

İşlem başarılı olduğunda yeni API anahtarınızın bulunduğu bir sayfa açılır.

  1. Örnek komut dosyasını Google Ads'deki yeni bir komut dosyasına yapıştırın.
  2. Girişteki API anahtarını yeni verilen anahtarla değiştirin ve e-posta adresi alanını düzenleyin.

Sorun giderme

Üçüncü taraf API'lerle çalışırken çeşitli nedenlerle hatalar oluşabilir. Örneğin:

  • İstemciler, sunucuya API tarafından beklenmeyen bir biçimde istek gönderiyor.
  • İstemciler, karşılaşılandan farklı bir yanıt biçimi bekliyor.
  • Geçersiz jeton veya anahtar kullanan ya da değerleri yer tutucu olarak bırakılan istemciler.
  • Kullanım sınırlarına ulaşan istemciler.
  • Geçersiz parametreler sağlayan istemciler.

Tüm bu durumlarda ve diğerlerinde, sorunun nedenini belirlemek için iyi bir ilk adım, hataya neden olan yanıtın ayrıntılarını incelemektir.

Yanıtları ayrıştırma

Varsayılan olarak, hata döndüren tüm yanıtlar (400 veya daha yüksek bir durum kodu) Google Ads komut dosyaları motoru tarafından oluşturulur.

Bu davranışı önlemek ve hatanın ve hata mesajının incelenmesine izin vermek için isteğe bağlı parametrelerin muteHttpExceptions özelliğini UrlFetchApp.fetch olarak ayarlayın. Örneğin:

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

Yaygın durum kodları

  • 200 OK, işlemin başarılı olduğunu gösterir. Yanıt beklenen verileri içermiyorsa şunları göz önünde bulundurun:

    • Bazı API'ler, hangi alanların, yanıt biçiminin veya her ikisinin kullanılacağını belirtmenize olanak tanır. Bu konuyla ilgili ayrıntılı bilgi için API belgelerini inceleyin.
    • Bir API'nin çağrılabilecek birden fazla kaynağı olabilir. Farklı bir kaynağın daha uygun olup olmayacağını ve ihtiyacınız olan verileri döndürüp döndürmeyeceğini belirlemek için belgelere bakın.
    • API, kod yazıldıktan sonra değişmiş olabilir. Açıklama için belgelere veya geliştiriciye başvurun.
  • 400 Bad Request genellikle sunucuya gönderilen isteğin biçimlendirmesinde veya yapısında bir sorun olduğu anlamına gelir. İsteği inceleyin ve beklentilere uygun olduğundan emin olmak için API spesifikasyonlarıyla karşılaştırın. İsteklerin nasıl inceleneceğiyle ilgili ayrıntılar için İstekleri denetleme bölümüne bakın.

  • 401 Unauthorized genellikle API'nin, yetkilendirme sağlanmadan veya başarıyla gerçekleştirilmeden çağrıldığı anlamına gelir.

    • API temel yetkilendirme kullanıyorsa Authorization başlığının oluşturulduğundan ve istekte sağlandığından emin olun.
    • API, OAuth 2.0 kullanıyorsa erişim jetonunun alındığından ve hamiline ait jeton olarak sağlandığından emin olun.
    • Yetkilendirmeyle ilgili diğer tüm varyasyonlar için istekte gerekli kimlik bilgilerinin sağlandığından emin olun.
  • 403 Forbidden, kullanıcının istenen kaynak için izni olmadığını gösterir.

    • Kullanıcıya gerekli izinlerin verildiğinden emin olun. Örneğin, dosya tabanlı bir istekte kullanıcıya bir dosyaya erişim izni verin.
  • 404 Not Found, istenen kaynağın mevcut olmadığı anlamına gelir.

    • API uç noktası için kullanılan URL'nin doğru olup olmadığını kontrol edin.
    • Bir kaynak getiriliyorsa referans verilen kaynağın mevcut olup olmadığını kontrol edin (örneğin, dosya tabanlı bir API için dosyanın mevcut olup olmadığı).

İstekleri inceleme

API yanıtları, isteğin hatalı biçimlendirildiğini gösterdiğinde (ör. 400 durum kodu) istekleri incelemek faydalı olur. İsteklerin incelenmesine yardımcı olmak için UrlFetchApp, fetch() yöntemine eşlik eden getRequest(url, params) adlı bir yönteme sahiptir.

Bu yöntem, sunucuya istek göndermek yerine gönderilecek olan isteği oluşturur ve ardından döndürür. Bu sayede kullanıcı, isteğin doğru göründüğünden emin olmak için isteğin öğelerini inceleyebilir.

Örneğin, isteğinizdeki form verileri birbirine eklenmiş birçok dizeden oluşuyorsa hata, bu form verilerini oluşturmak için oluşturduğunuz işlevde olabilir. En basit haliyle:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

isteğin öğelerini incelemenize olanak tanır.

İstekleri ve yanıtları günlüğe kaydetme

Üçüncü taraf API'sine gönderilen istekleri ve yanıtları inceleme sürecinin tamamına yardımcı olmak için aşağıdaki yardımcı işlev, hem istekleri hem de yanıtları günlüğe kaydetmek üzere UrlFetchApp.fetch() yerine kullanılabilir.

  1. Kodunuzdaki tüm UrlFetchApp.fetch() örneklerini logUrlFetch() ile değiştirin.

  2. Komut dosyanızın sonuna aşağıdaki işlevi ekleyin.

    function logUrlFetch(url, opt_params) {
     const params = opt_params || {};
     params.muteHttpExceptions = true;
     const request = UrlFetchApp.getRequest(url, params);
     console.log('Request:       >>> ' + JSON.stringify(request));
     const response = UrlFetchApp.fetch(url, params);
     console.log('Response Code: <<< ' + response.getResponseCode());
     console.log('Response text: <<< ' + response.getContentText());
     if (response.getResponseCode() >= 400) {
       throw Error('Error in response: ' + response);
     }
     return response;
    }
    

Komut dosyanız yürütülürken tüm istek ve yanıtların ayrıntıları konsola kaydedilir. Bu sayede hata ayıklama işlemi daha kolay hale gelir.

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities