Üçüncü Taraf API'ler

Google Ads komut dosyalarının güçlü özelliklerinden biri, üçüncü taraf API'lerinden gelen verilerle ve hizmetlerle entegrasyon yapabilmesidir.

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

  • HTTP isteği gönderme: Harici API'lere erişmek için UrlFetchApp nasıl kullanılır?
  • 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 işlenmesi.

Ayrıca, bu kavramları gösteren popüler API'ler için örnek de ekledik.

UrlFetchApp ile veri getirme

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

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

İstekte bulunun

OpenWeatherMap dokümanlarında, mevcut hava durumunu istemek için kullanılacak biçim ş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ıya özgüdür. Bu anahtar, kaydolma işlemiyle elde edilir.

Kaydolduktan sonra anahtarı kullanarak aşağıdaki şekilde istek gönderilebilir:

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 uzun bir JSON metni dizesinin yazılmasıyla sonuçlanır.

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

JSON verileri

Birçok API, yanıtları JSON biçiminde sağlar. Bu, JavaScript nesnelerinin basit bir serileştirmesini temsil eder. Böylece nesneler, diziler ve temel türler dize olarak temsil edilebilir ve aktarılabilir.

OpenWeatherMap'ten döndürülen JSON dizelerini JavaScript nesnesine dönüştürmek için yerleşik JSON.parse yöntemini kullanın. Yukarıdaki örnekten devam edersek:

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'ler genellikle sık sık değiştiği ve beklenmedik yanıt değerleri oluşturduğu için komut dosyalarınızda üçüncü taraf API'lerle çalışırken hata işleme önemli bir konudur. Örneğin:

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

HTTP durum kodları

Beklenmedik yanıtlar olabileceğinden HTTP durum kodunu incelemeniz gerekir. Varsayılan olarak, UrlFetchApp bir HTTP hata koduyla karşılaşıldığında istisna atar. Bu davranışı değiştirmek için aşağıdaki örnekte gösterildiği gibi isteğe bağlı bir parametre göndermeniz 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 geliştiriciler genellikle komut dosyalarını etkileyebilecek değişikliklerden hemen haberdar olmaz. Ö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 yararlı 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

OpenWeatherMap ile tanıtım amaçlı örnek yalnızca verileri getiriyordu. Uzak sunucuda durumu değiştirmeyen API çağrıları genellikle 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ı açıklamak 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ı olan Slack ile entegrasyon gösterilmektedir.

Slack'ı kurma

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

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

Gelen WebHooks Entegrasyonu Ekle'yi tıklayıp talimatları uygulayarak gelen webhook ayarlayın. Bu işlem, mesajlaşma için kullanılacak bir URL yayınlar.

POST isteği gönderme

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

  • method: Daha önce de belirtildiği gibi, bu varsayılan olarak GET değerine ayarlanır ancak burada bu değeri geçersiz kılıp POST olarak belirleriz.

  • payload: Bu, POST isteği kapsamında sunucuya gönderilecek verilerdir. Bu örnekte Slack, Slack dokümanlarında açıklandığı gibi JSON biçiminde serileştirilmiş bir nesne bekler. Bunun için JSON.stringify 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

Yukarıdaki örnekte, Slack'a gelen mesajları etkinleştirmek için gereken minimum değer gösterilmektedir. Genişletilmiş bir örnek, bir gruba Kampanya Performansı Raporu oluşturma ve gönderme işleminin yanı sıra bazı biçimlendirme ve görüntüleme seçeneklerini gösterir.

Gelen mesaj

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

Form verileri

Yukarıdaki örnekte, POST isteği için payload özelliği olarak bir JSON dizesi kullanılmıştır.

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ğer haritası):

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

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

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

    Ayrıca, istek için Content-Type üstbilgisi application/x-www-form-urlencoded olarak ayarlanır.

Bazı API'ler, POST istekleri gönderirken form verilerinin kullanılmasını gerektirir. Bu nedenle, JavaScript nesnelerinden form verilerine otomatik dönüşüm özelliğini 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 üst bilgilerine kodlanmış bir kullanıcı adı ve şifre eklenerek yapılır.

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ını ve şifreyi iki nokta üst üste işaretiyle (ör. username:password) birleştirerek şifre öbeğini oluşturun.
  2. Parolanızı Base64 olarak kodlayın. Örneğin, username:password yerine dXNlcm5hbWU6cGFzc3dvcmQ= yazın.
  3. İsteğe Authorization üstbilgisi ekleyin. Authorization: Basic <encoded passphrase> biçiminde olmalıdır.

Aşağıdaki snippet'te, Google Ads komut dosyalarında bu işlemin nasıl yapılacağı gösterilmektedir:

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 aracılığıyla SMS mesajlarının gönderilmesini ve alınmasını kolaylaştıran bir hizmettir. Bu örnekte mesaj gönderme 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. Hata bildirimi için komut dosyasında belirtildiği şekilde 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 korumalı alan numaraları ekleyin.
  6. Hem gönderen olarak görünecek numarayı hem de alıcı numarasını ekleyin.
  7. Senaryoda PLIVO_SRC_PHONE_NUMBER değerini, yeni kaydedilen korumalı alan numaralarından birine güncelleyin. Bu, uluslararası ülke kodunu içermelidir. Örneğin, Birleşik Krallık numarası için 447777123456.

Twilio

Twilio, API'si üzerinden 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 yerine kontrol panelindeki numarayı girin. Bu, Twilio tarafından mesaj göndermek için yetkilendirilmiş 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 vardır. OAuth ise üçüncü taraf uygulamalarına, söz konusu üçüncü taraf uygulamasına özgü kimlik bilgilerini kullanarak kullanıcının hesabına ve verilerine erişim izni verilmesine olanak tanır. Ayrıca, erişimin kapsamı da ilgili uygulamaya özeldir.

OAuth 1.0 hakkında bilgi edinmek için OAuth Core kılavuzuna göz atın. Özellikle 6. OAuth ile kimlik doğrulama. Tam üç ayaklı 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 erişim jetonuyla değiştirir.
  4. Sonraki tüm kaynak isteklerinde erişim jetonu, imzalı bir istekte kullanılır.

Üçüncü taraf hizmetlerinin OAuth 1.0'u kullanıcı etkileşimi olmadan kullanması (ör. Google Ads komut dosyalarının gerektirdiği şekilde) için 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çmesini sağlar. Buna tek ayaklı OAuth 1.0 denir.

OAuth1

Google Ads komut dosyalarında OAuth 1.0

Google Ads komut dosyalarında her komut dosyası genellikle bir uygulama olarak yorumlanır. Hizmetin konsolu/yönetim ayarları sayfasından 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 ayaklı 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, popüler API'lerde kullanıcı verilerine erişim sağlamak için kullanılır. Belirli bir üçüncü taraf hizmetinin hesabının sahibi, belirli uygulamalara kullanıcı verilerine erişme izni verir. Bu yöntemin avantajları şunlardır:

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

Google Ads komut dosyalarında OAuth 2.0 özellikli hizmetleri kullanmak için birkaç adım uygulamanız gerekir:

Komut dosyanızdan hariç

Google Ads Komut Dosyaları'nın üçüncü taraf API üzerinden kullanıcı verilerinize erişmesi için yetki verin. Çoğu durumda bu işlem, üçüncü taraf hizmetinin konsolunda bir uygulama oluşturmayı içerir. Bu uygulama, Google Ads komut dosyanızı temsil eder.

Google Ads komut dosyası uygulamasına hangi erişim haklarının verilmesi gerektiğini belirtirsiniz ve genellikle bir istemci kimliği atanır. Bu sayede, OAuth 2 aracılığıyla üçüncü taraf hizmetindeki verilerinize hangi uygulamaların erişebileceğini ve bu verilerin hangi yönlerini görebildiklerini ya da değiştirebileceklerini kontrol edebilirsiniz.

Komut dosyanızda

Uzaktan sunucuyla yetkilendirme. Sunucunun izin verdiği izin türüne bağlı olarak, akış olarak bilinen farklı bir adım dizisinin uygulanması gerekir. Ancak tüm bu adımlar sonunda, sonraki tüm istekler için söz konusu oturumda kullanılacak bir erişim jetonu oluşturulur.

API isteği gönderme Her istekle birlikte erişim jetonunu iletin.

Yetkilendirme akışları

Her bağış türü ve ilgili akış farklı kullanım senaryolarına hitap eder. Örneğin, bir kullanıcı etkileşimli bir oturumda yer aldığında, uygulamanın kullanıcı olmadan arka planda çalışmasının gerektiği senaryoya kıyasla farklı bir akış kullanılır.

API sağlayıcılar, kabul edecekleri izin türlerine karar verir. Bu karar, kullanıcının API'sini entegre etme işlemine nasıl devam edeceğine yön verir.

Uygulama

Tüm farklı OAuth akışlarında amaç, isteklerin kimliğini doğrulamak için oturumun geri kalanında 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 alan ve depolayan ve kimliği doğrulanmış istekleri kolaylaştıran bir nesne döndürür.

Genel kullanım şekli şu şekildedir:

// 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 atama

İstemci kimlik bilgisi izni, OAuth2 akışının daha basit formlarından biridir. Bu akışta uygulama, zaman sınırlı bir erişim jetonu verilmesi karşılığında uygulamaya özgü bir kimlik ve gizli anahtar alışverişinde bulunur.

İ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 verme

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

Yenileme jetonu

Yenileme jetonu alma

Yenileme jetonu verme işlemiyle arasındaki fark, istemci kimlik bilgisi verme işlemi için gereken ayrıntıların uygulama yapılandırmasından (ör. hizmetin kontrol panelinden) gelmesine karşın yenileme jetonunun, kullanıcı etkileşimi gerektiren yetkilendirme kodu verme gibi daha karmaşık bir akış kapsamında 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 iznini adım adım tamamlamasına olanak tanıyan 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. Örneğin:

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

OAuth Oyun Alanı

Yenileme jetonu almak için komut dosyası kullanma

Akış tamamlama işleminin komut dosyası tabanlı bir alternatifi, yeniden yenileme jetonu oluşturma örneğinde sunulmaktadır.

Yenileme jetonu kullanımı

İlk yetkilendirme yapıldıktan sonra hizmetler, istemci kimlik bilgileri akışına benzer şekilde kullanılabilecek bir yenileme jetonu yayınlayabilir. Aşağıda iki örnek verilmiştir:

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şturup 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. API Konsolu'nda yeni bir proje oluşturun ve DoubleClick kılavuzundaki prosedürü uygulayarak istemci kimliği, istemci gizlisi ve yenileme jetonu alın. Bu işlem sırasında DoubleClick Search API'yi etkinleştirdiğinizden emin olun.
  2. Örnek komut dosyasını Google Ads'deki yeni bir komut dosyasına yapıştırın.
  3. Kod listelemesinin altına örnek OAuth2 kitaplığını 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ı Yürütme API'si örneği

Bu örnekte, Apps Komut Dosyası Yürütme API'si kullanılarak Apps Komut Dosyası'nda bir işlevin yürütülmesi gösterilmektedir. Bu, Apps Komut Dosyası'nın Google Ads komut dosyalarından çağrılmasına olanak tanır.

Apps Komut Dosyası komut dosyası oluşturma

Yeni bir komut dosyası oluşturun. Aşağıdaki örnekte, Drive'daki 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. API Konsolu'na gitmek için proje adını tıklayın.
  4. API'ler ve Hizmetler'e gidin.
  5. Uygun API'leri (bu durumda Drive API ve Apps Script Execution API) etkinleştirin.
  6. Menüdeki Kimlik bilgileri öğesinden OAuth kimlik bilgileri oluşturun.
  7. Komut dosyanıza geri dönüp Yayınla > API Yürütülebilir Dosyası Olarak Dağıt'ı seçerek komut dosyasını çalıştırılmak ü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 listelemesinin altına örnek OAuth2 kitaplığını 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ı

Yukarıdaki izin türlerine alternatif olarak hizmet hesapları kavramı kullanılabilir.

Hizmet hesapları, kullanıcı verilerine erişmek için kullanılmadıkları için yukarıdakilerden farklıdır: Kimlik doğrulamasından sonra istekler, projenin sahibi olabilecek kullanıcı olarak değil, hizmet hesabı tarafından uygulama adına gönderilir. Ö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 proje sahibi tarafından erişilemez.

Google Natural Language API örneği

Natural Language API, metin için duygu analizini ve varlık analizini sağlar.

Bu örnekte, başlık veya açıklama dahil olmak üzere reklam metninin duygusal durumunun hesaplanması gösterilmektedir. Bu, mesajın ne kadar olumlu olduğunu ve mesajın büyüklüğünü ölçer: Kek satıyoruz mu yoksa Londra'nın en iyi keklerini satıyoruz mu? Hemen satın alın!

Komut dosyasını ayarlama
  1. API Konsolu'nda yeni bir proje oluşturun
  2. Natural Language API'yi etkinleştirin
  3. Proje için faturalandırmayı etkinleştirin.
  4. Hizmet hesabı oluşturun. Kimlik bilgileri JSON dosyasını indirin.
  5. Örnek komut dosyasını Google Ads'de yeni bir komut dosyasına yapıştırın.
  6. Ayrıca, kod listelemesinin altına örnek OAuth2 kitaplığını 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ında bulunan anahtar. -----BEGIN PRIVATE KEY... tarihinde başlar ve ...END PRIVATE KEY-----\n tarihinde biter.

API yanıtları

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

JSON

JSON, yanıt biçimi olarak kullanmak için genellikle XML'den daha basittir. Ancak yine de ortaya çıkabilecek bazı sorunlar vardır.

Yanıt doğrulaması

API çağrısından başarılı bir yanıt aldıktan sonra, JSON dizesini JavaScript nesnesine dönüştürmek için genellikle JSON.parse kullanılır. Bu noktada, ayrıştırmanın 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'nin kontrolü sizde 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

Doğrulama

XML, API oluşturmak için hâlâ popüler bir biçimdir. API çağrısından gelen bir 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ılar ve buna göre istisnalar oluşturur ancak XML'i bir şemaya göre doğrulama olanağı sağlamaz.

Kök öğe

XML dokümanı başarıyla ayrıştırıldığında 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çili maçların futbol sonuçlarını almak için Sportradar API kullanılmaktadır. XML yanıtı aşağıdaki biçimdedir:

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

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

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

Aşağıdaki örnekte, yukarıdaki belge snippet'inde <matches> öğesine nasıl erişileceği gösterilmektedir:

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

Değerler elde etme

Futbol programındaki örnekte:

<match status="..." category="..." ... >
  ...
</match>

Özellikler aşağıdaki gibi alınabilir:

const status = matchElement.getAttribute('status').getValue();

Bir öğenin içinde bulunan metin, getText() kullanılarak okunabilir ancak bir öğenin birden fazla metin alt öğesi varsa bunlar birleştirilir. Birden fazla metin alt öğesinin olması muhtemel durumlarda getChildren() kullanarak her alt öğeyi iterasyonla gezmeyi düşünebilirsiniz.

Sportradar örneği

Bu tam Sportradar örneği, futbol maçlarının (özellikle de İngiliz Premier League maçlarının) ayrıntılarını alma işlemini göstermektedir. Soccer API, Sportradar tarafından sunulan çok çeşitli spor feed'lerinden biridir.

Sportradar hesabı oluşturma
  1. Sportradar geliştirici sitesine gidin.
  2. Deneme hesabına kaydolun.
  3. Kaydolduktan sonra hesabınızda oturum açın.
  4. Giriş yaptıktan sonra MyAccount'a gidin.

Sportradar, farklı sporları farklı API'lere ayırır. Örneğin, Soccer API'ye erişim satın alabilir ancak Tennis API'ye erişim satın almayabilirsiniz. Oluşturduğunuz her uygulamanın farklı sporlar ve farklı anahtarları olabilir.

  1. Uygulamalar bölümünde Yeni uygulama oluştur'u tıklayın. Uygulamaya bir ad ve açıklama girin, web sitesi alanını boş bırakın.
  2. Yalnızca Soccer Trial Europe v2 için yeni bir anahtar yayınla'yı seçin.
  3. Uygulamayı Kaydet'i tıklayın.

İşlem başarıyla tamamlandığında 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ı yukarıda elde edilen anahtarla değiştirin ve e-posta adresi alanını düzenleyin.

Sorun giderme

Üçüncü taraf API'lerle çalışırken çeşitli nedenlerden dolayı hatalar meydana gelebilir. Örneğin:

  • Sunucuya API tarafından beklenmeyen bir biçimde istek gönderen istemciler.
  • Karşılaştığından farklı bir yanıt biçimi bekleyen istemciler.
  • Geçersiz jetonlar veya anahtarlar ya da yer tutucu olarak bırakılan değerler kullanan istemciler.
  • Kullanım sınırlarını aşan istemciler.
  • Geçersiz parametreler sağlayan istemciler.

Bu ve diğer tüm durumlarda, sorunun nedenini belirlemenin 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 dosyası motoru tarafından atılır.

Bu davranışı önlemek ve hatanın ve hata mesajının incelenmesine izin vermek için isteğe bağlı parametrelerin muteHttpExceptions mülkünü 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, başarıyı gösterir. Yanıt, beklenen verileri içermiyorsa aşağıdakileri göz önünde bulundurun:

    • Bazı API'ler, hangi alanların ve/veya yanıt biçiminin kullanılacağının belirtilmesine olanak tanır. Bu konuda ayrıntılı bilgi için API belgelerini inceleyin.
    • Bir API'nin çağrılabilecek birden fazla kaynağı olabilir. Farklı bir kaynağın kullanılmasının daha uygun olup olmadığını ve ihtiyacınız olan verileri döndürüp döndürmeyeceğini belirlemek için dokümanlara bakın.
    • Kod yazıldıktan sonra API değişmiş olabilir. Daha fazla bilgi için dokümanlara veya geliştiriciye bakın.

  • 400 Bad Request genellikle sunucuya gönderilen isteğin biçimlendirmesinde veya yapısında bir sorun olduğu anlamına gelir. Beklentilere uygun olduğundan emin olmak için isteği inceleyin ve API özellikleriyle karşılaştırın. İstekleri incelemeyle ilgili ayrıntılar için İstekleri inceleme bölümüne bakın.

  • 401 Unauthorized genellikle API'nin yetkilendirme sağlanmadan veya başarılı bir şekilde 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'de OAuth 2.0 kullanılıyorsa erişim jetonunun elde edildiğinden ve hamiline ait jeton olarak sağlandığından emin olun.
    • Yetkilendirmeyle ilgili diğer varyasyonlar için istekle ilgili 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 (ör. 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 atıfta bulunulan kaynağın mevcut olup olmadığını kontrol edin (örneğin, dosya tabanlı bir API için dosyanın mevcut olup olmadığını).

İstekleri inceleme

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

Bu yöntem, sunucuya istek göndermek yerine gönderilecek isteği oluşturur ve 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ğinizde form verileri birbirine bağlanmış 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ği incelemenize olanak tanır.

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

Üçüncü taraf API'ye yapılan isteklerin ve yanıtların incelenmesi sürecinin tamamına yardımcı olmak için aşağıdaki yardımcı işlev, hem isteklerin hem de yanıtların günlüğe kaydedilmesi amacıyla 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üldüğünde tüm istek ve yanıtların ayrıntıları konsola kaydedilir. Bu sayede hata ayıklama işlemi daha kolay olur.