Üçüncü Taraf API'ler

Google Ads komut dosyalarının güçlü bir özelliği, üçüncü taraf API'lerin sağladığı veri 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 oluşturma: Harici API'lere erişmek için UrlFetchApp nasıl kullanılır?
  • Kimlik doğrulama: Bazı yaygın kimlik doğrulama senaryolarını ele aldık.
  • Yanıtları ayrıştırma: Döndürülen JSON ve XML verilerinin nasıl işleneceği.

UrlFetchApp ile veri getir

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

Aşağıdaki örnekte, OpenWeatherMap'ten hava durumu verilerinin getirilmesi gösterilmektedir. OpenWeathermap'i seçtik, bunun nedeni nispeten basit yetkilendirme şeması ve API'dir.

İstekte bulunun

OpenWeatherMap belgeleri, mevcut hava durumu bilgilerini istemek için gereken biçimi aşağıdaki gibi belirtir:

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 elde edilir.

Kaydolduktan sonra, anahtarı kullanan bir istek aşağıdaki şekilde 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 çalıştırılması, Google Ads komut dosyalarındaki günlük penceresine yazılan uzun bir JSON metni dizesine neden olur.

Sonraki adım, bunu komut dosyanızda kullanılabilen 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 edilip aktarılabilir.

Bir JSON dizesini (OpenWeatherMap'ten döndürülen dize gibi) tekrar JavaScript nesnesine dönüştürmek için yerleşik JSON.parse yöntemini kullanın. Yukarıdaki ö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 genellikle sık sık değiştiğinden ve beklenmedik yanıt değerleri oluşturduğundan, komut dosyalarınızda üçüncü taraf API'leriyle çalışırken hataların ele alınması önemli bir noktadır. Örneğin:

  • API'nin URL'si veya parametreleri bilginiz olmadan değişebilir.
  • API anahtarınızın (veya başka bir kullanıcı kimlik bilginizin) süresi dolabilir.
  • Yanıtın biçimi haber verilmeden değiştirilebilir.

HTTP durum kodları

Beklenmeyen yanıt verme olasılığı nedeniyle HTTP durum kodunu incelemeniz gerekir. Varsayılan olarak, HTTP hata koduyla karşılaşılırsa UrlFetchApp istisna oluşturur. Bu davranışı değiştirmek için aşağıdaki örnekte olduğu gibi isteğe bağlı bir parametrenin iletilmesi 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'ler değiştiğinde geliştiriciler komut dosyalarını etkileyebilecek değişikliklerden genellikle 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 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

OpenWeatherMap'in kullanıldığı giriş örneği, yalnızca veri getirmiştir. Genellikle uzak sunucudaki durumu değiştirmeyen API çağrıları HTTP GET yöntemini kullanır.

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

Aşağıdaki örnekte, POST çağrılarını UrlFetchApp ile kullanmayı göstermek amacıyla, Slack kullanıcılarına ve gruplarına Slack mesajı göndermek için ortak çalışmaya dayalı bir mesajlaşma uygulaması olan Slack ile entegrasyon gösterilmektedir.

Slack'i kurma

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

Önceki örnekte verilen OpenWeatherMap'te olduğu gibi, mesaj gönderebilmek için bir jeton alınması gerekir. Slack, ekibinize mesaj göndermenize olanak tanıyan Gelen Webhook adı verilen benzersiz bir URL sağlar.

Gelen Web Kancaları Entegrasyonu Ekle'yi tıklayıp talimatları uygulayarak Gelen Webhook'u ayarlayın. İşlem, mesajlaşma için kullanılacak bir URL yayınlamalıdır.

POST isteği gönderme

Gelen Webhook'unuzu ayarladıktan sonra POST isteğinde bulunmak için UrlFetchApp.fetch öğesine iletilen options parametresinde bazı ek özelliklerin kullanılması yeterlidir:

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

  • payload: POST isteğinin bir parçası olarak sunucuya gönderilecek veridir. Bu örnekteki Slack, Slack belgelerinde açıklandığı gibi JSON biçiminde serileştirilmiş bir nesne olmasını 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'e gelen iletileri etkinleştirmek için gereken minimum değer gösterilmektedir. Genişletilmiş bir örnek, Kampanya Performans Raporu'nun oluşturulup bir gruba gönderilmesinin yanı sıra bazı biçimlendirme ve görüntüleme seçeneklerini gösterir.

Gelen mesaj

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

Form verileri

Yukarıdaki örnek, POST isteği için payload özelliği olarak bir JSON dizesinin kullanımını göstermektedir.

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

  • payload bir dize olduğunda dize bağımsız değişkeni, isteğin gövde metni olarak gönderilir.

  • payload bir nesne olduğunda, örneğin değer haritası:

    {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 nesnelerinden form verilerine otomatik dönüştürme unutulmamalıdı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 başlıklarına 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 gerekir:

  1. Kullanıcı adı ve şifreyi iki nokta üst üste işaretiyle birleştirerek parolayı oluşturun (örneğin, username:password).
  2. Base64, parolayı kodlar. Örneğin, username:password, dXNlcm5hbWU6cGFzc3dvcmQ= olur.
  3. İsteğe Authorization: Basic <encoded passphrase> formunda bir Authorization başlığı ekleyin

Aşağıdaki snippet'te bunun Google Ads Komut Dosyaları'nda 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);

Plivo

Plivo, API'leri aracılığıyla SMS mesajı gönderip almayı kolaylaştıran bir hizmettir. Bu örnek mesaj göndermeyi göstermektedir.

  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 e-posta adresinizi komut dosyasında belirtildiği şekilde 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. Komut dosyasındaki PLIVO_SRC_PHONE_NUMBER değerini, yeni kaydedilen korumalı alan numaralarından biriyle güncelleyin. Buna, uluslararası ülke kodu da eklenmelidir. Örneğin, Birleşik Krallık'taki bir numara için 447777123456.

Twilio

Twilio, API'leri aracılığıyla SMS mesajı gönderip almayı kolaylaştıran bir başka hizmettir. Bu örnek mesaj göndermeyi göstermektedir.

  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 numarasını kontrol panelindeki numarayla değiştirin. Bu, Twilio tarafından mesaj göndermek için yetkilendirilen numaradır.

OAuth 1.0

Çoğu popüler hizmet, kimlik doğrulama için OAuth kullanmaktadır. OAuth'un farklı çeşitleri ve versiyonları mevcuttur.

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ının, üçüncü taraf uygulamasına özel kimlik bilgilerini kullanarak kullanıcının hesabına ve verilerine erişmesine izin verilmesine olanak tanır. Ayrıca, erişimin kapsamı da söz konusu uygulamaya özgü olacaktır.

OAuth 1.0 arka planı için OAuth Temel kılavuzuna göz atın. Özellikle bkz. 6. OAuth ile kimlik doğrulama başlıklı makaleyi inceleyin. 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 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, kullanıcı etkileşimi olmadan (örneğin, Google Ads komut dosyalarının gerektirdiği) OAuth 1.0'ı kullanması 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 gitmesini sağlar. Bu, tek aşamalı OAuth 1.0 olarak bilinir.

OAuth1

Google Ads komut dosyalarında OAuth 1.0

Google Ads komut dosyaları için her bir komut dosyası genellikle bir uygulama olarak yorumlanır. Hizmetin konsol/yönetim ayarları sayfasından genellikle aşağıdaki işlemler gerekir:

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

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 hizmetindeki hesabın sahibi, belirli uygulamalara kullanıcı verilerine erişme izni verir. İşletme sahibinin avantajları:

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

Google Ads komut dosyalarında OAuth 2.0'ın etkin olduğu hizmetleri kullanmak için izlemeniz gereken birkaç adım vardır:

Komut dosyanızın dışında

Google Ads Komut Dosyaları'na, üçüncü taraf API üzerinden kullanıcı verilerinize erişim yetkisi 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 buna genellikle bir istemci kimliği atanır. Böylece OAuth 2 aracılığıyla üçüncü taraf hizmetteki verilerinize hangi uygulamaların erişebileceğini ve bu verilerin hangi yönlerini görebileceklerini veya değiştirebileceklerini kontrol edebilirsiniz.

Komut dosyanızda

Uzak sunucuyla yetkilendirin. Sunucunun izin verdiği izin türüne bağlı olarak, akış olarak bilinen farklı bir adım kümesinin izlenmesi gerekir. Ancak tüm adımlarda, sonraki tüm istekler için söz konusu oturumda kullanılacak bir erişim jetonu verilir.

API isteklerinde bulunma. Her istekle birlikte erişim jetonunu iletin.

Yetkilendirme akışları

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

API sağlayıcıları hangi izin türlerini kabul edeceklerine karar verir ve bu, kullanıcının API'lerini entegre ederken nasıl ilerleyeceğini yönlendirir.

Uygulama

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

Örnek kitaplığı, farklı her bir 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 saklayan ve kimliği doğrulanmış istekleri kolaylaştıran bir nesne döndürür.

Genel kullanım şekli şö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);

Müşteri kimlik bilgileri verme

İstemci kimlik bilgisi verme, daha basit OAuth2 akışı biçimlerinden biridir. Bu akışta uygulama, sınırlı süreli bir erişim jetonu verilmesi karşılığında uygulamaya özel bir kimlik ve gizli anahtarı değiştirir.

İ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

Jeton iznini yenile

Sunucuya yapılan basit bir istek, oturumda kullanılabilecek bir erişim jetonu döndürdüğünden, yenileme jetonu izni istemci kimlik bilgileri verme işlemine benzer.

Yenileme jetonu

Yenileme jetonu alma

Yenileme jetonu izninin farkı, istemci kimlik bilgileri izni için gerekli ayrıntıların uygulama yapılandırmasından gelmesidir (ör. hizmetin kontrol panelinde), yenileme jetonunun kullanıcı etkileşimi gerektiren yetkilendirme kodu izni gibi daha karmaşık bir akışın bir parçası olarak verilmesidir:

Yetkilendirme kodu

Yenileme jetonu almak için OAuth Playground'u kullanma

OAuth2 oyun alanı, kullanıcının yenileme jetonu almak için yetkilendirme kodu iznini adım adım incelemesine olanak tanıyan bir kullanıcı arayüzü sağlar.

Sağ üstteki ayarlar düğmesi, aşağıdakiler de dahil olmak üzere OAuth akışında kullanılacak tüm parametreleri tanımlamanıza olanak tanı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 jetonuyla kullanılır.
  • client ID and secret [istemci kimliği ve gizli anahtar]: Uygulamanın kimlik bilgileri.

OAuth Playground

Yenileme jetonu almak için komut dosyası kullanma

Akışı tamamlamanın komut dosyası tabanlı bir alternatifi, yenileme jetonu oluşturma örneğinde mevcuttur.

Jeton kullanımını yenile

İlk yetkilendirme tamamlandıktan sonra hizmetler, istemci kimlik bilgileri akışına benzer bir ş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ılabilecek bir API örneğidir. Bu örnekte, bir komut dosyası rapor oluşturur ve döndürür. Gerçekleştirilebilecek diğer işlemlerin tüm ayrıntıları için Search Ads 360 API referansına bakın.

Komut dosyasını oluşturun
  1. API Konsolu'nda yeni bir proje oluşturun ve DoubleClick kılavuzundaki prosedürü izleyerek bir istemci kimliği, istemci gizli anahtarı ve yenileme jetonu alın. Ardından, 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. Örnek OAuth2 kitaplığını 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ı 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ını sağlar.

Apps 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ırın
  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 örnekte, Drive API ve Apps Komut Dosyası Yürütme API'si) etkinleştirin.
  6. OAuth kimlik bilgilerini menüdeki Credentials (Kimlik Bilgileri) öğesinden oluşturun.
  7. Tekrar komut dosyanıza dönüp Yayınla > API Yürütülebilir Olarak Dağıt seçeneğinden yürütme için komut dosyasını yayınlayın.
Google Ads komut dosyasını oluşturun
  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ı 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 hibe türlerine alternatif olarak hizmet hesapları kavramı kullanılabilir.

Hizmet hesapları, kullanıcı verilerine erişmek için kullanılmaması açısından yukarıdakinden farklıdır: Kimlik doğrulamasından sonra istekler, projenin sahibi olabilecek kullanıcı olarak değil, uygulama adına Hizmet Hesabı tarafından gönderilir. Örneğin, hizmet hesabı, dosya oluşturmak için Drive API'yi kullanacaksa bu hizmet hesabına ait olur ve varsayılan olarak projenin sahibi bu hesaba erişemez.

Google Natural Language API örneği

natural Language API, metinler için hassas analizi ve varlık analizi sunar.

Bu örnekte, başlık veya açıklama dahil olmak üzere reklam metni için duyarlılığın hesaplanması gösterilmektedir. Bu, mesajın ne kadar olumlu olduğuna ve mesajın büyüklüğüne dair bir ölçüm sağlar: Hangisi daha iyi? Pasta satıyoruz veya Londra'daki en iyi pastaları satıyoruz. Hemen satın alın!

Komut dosyasını ayarlayın
  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 listesinin altına örnek OAuth2 kitaplığını yapıştırın.
  7. Gerekli değerleri değiştirin:
    • serviceAccount: Hizmet Hesabının e-posta adresidir (örneğin, xxxxx@yyyy.iam.gserviceaccount.com).
    • key: Hizmet Hesabı'nı oluştururken indirilen JSON dosyasından alınan anahtar. -----BEGIN PRIVATE KEY... tarihinde başlayacak ve ...END PRIVATE KEY-----\n tarihinde sona erecek.

API yanıtları

API'ler çeşitli biçimlerde veriler döndürebilir. Bunların en önemlisi, XML ve JSON'dir.

JSON

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

Yanıt doğrulaması

API'ye yapılan çağrıdan başarılı bir yanıt aldıktan sonra, tipik olarak sonraki adım JSON.parse dizesini kullanarak JSON dizesini bir JavaScript nesnesine dönüştürmektir. Bu noktada, ayrıştırmanın başarısız olduğu bir 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 var 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 yanıtlar, 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 uygun şekilde istisnalar atsa da XML'i bir şemaya göre doğrulama imkanı sağlamaz.

Kök öğe

XML belgesinin başarılı bir şekilde ayrıştırıldığı göz önünde bulundurulduğunda 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 Sportradar API, seçilen maçlar için futbol sonuçlarını elde etmek amacıyla kullanılmıştır. XML yanıtı aşağıdaki biçimi alır:

<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:

  • Ad alanı özelliğini belgeden çıkarın.
  • Alt öğelere geçerken ve bunlara erişirken bu ad alanını kullanın.

Aşağıdaki örnekte, yukarıdaki doküman 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ğer elde etme

Futbol programından alınan örneğe göre:

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

Özellikler alınabilir. Örneğin:

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

Bir öğenin içerdiği metinler, getText() kullanılarak okunabilir ancak bir öğenin birden fazla metin alt öğesi olduğunda bunlar birleştirilir. Birden fazla metnin alt öğeleri olabileceği durumlarda getChildren() kullanmayı ve her alt öğe için yineleme yapmayı düşünün.

Sportradar örneği

Bu Sportradar örneğinde, futbol maçları, özellikle de İngiltere Premier Ligi maçlarıyla ilgili ayrıntılar yer almaktadır. Soccer API, Sportradar'ın sunduğu çok çeşitli spor feed'lerinden biridir.

Sportradar hesabı oluşturun
  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 alamazsınız. Oluşturduğunuz her Uygulamanın, kendisiyle ilişkilendirilmiş farklı sporları ve farklı anahtarları olabilir.

  1. Uygulamalar altında Yeni bir uygulama oluştur'u tıklayın. Uygulamaya bir ad ve açıklama verin, web sitesi alanını dikkate almayın.
  2. Yalnızca Futbol Denemesi Avrupa v2 için yeni bir anahtar yayınlama'yı seçin.
  3. Başvuruyu Kaydet'i tıklayın.

İşlem başarılı olduktan sonra, 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ıdan elde edilen anahtarla değiştirin ve e-posta adresi alanını düzenleyin.

Sorun giderme

Üçüncü taraf API'leriyle çalışırken çeşitli nedenlerle hatalar ortaya çıkabilir. Örneğin:

  • İstemcilerin, API'nin beklemediği bir biçimde sunucuya istek göndermesi.
  • Karşılaşılandan farklı bir yanıt biçimi bekleyen müşteriler.
  • Geçersiz jetonlar veya anahtarlar kullanan istemciler ya da yer tutucu olarak bırakılan değerler.
  • Kullanım sınırına ulaşan müşteriler.
  • Geçersiz parametreler sağlayan istemciler.

Bunların tümü ve diğerlerinde, sorunun nedenini belirlemenin iyi bir ilk adımı, hataya neden olan yanıtın ayrıntılarını incelemektir.

Yanıtları ayrıştır

Varsayılan olarak, hata (400 veya üzeri bir durum kodu) döndüren tüm yanıtlar Google Ads komut dosyası motoru tarafından yayınlanır.

Bu davranışı önlemek ve hata ile 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 başarı olduğunu gösterir. Yanıt beklenen verileri içermiyorsa şunları göz önünde bulundurun:

    • Bazı API'ler hangi alanların ve/veya yanıt biçiminin kullanılacağının belirtilmesine izin verir. Bu konuyla ilgili ayrıntılı bilgi için API belgelerine göz atın.
    • Bir API'nin çağrılabilecek birden fazla kaynağı olabilir. Farklı bir kaynağın kullanılmasının daha uygun olup olmayacağını belirlemek için belgeleri inceleyin ve ihtiyacınız olan verileri size döndürecektir.
    • Kod yazıldıktan sonra API değişmiş olabilir. Açıklama için belgelere veya geliştiriciye danışın.

  • 400 Bad Request genellikle sunucuya gönderilen isteğin biçimlendirmesinde veya yapısında bir şeylerin doğru olmadığı anlamına gelir. İsteği inceleyin ve API spesifikasyonlarıyla karşılaştırarak beklentilere uygun olduğundan emin olun. İsteklerin nasıl inceleneceğiyle 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ıyla uygulanmadan ç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 varyasyonlarda istek için gerekli kimlik bilgilerinin sağlandığından emin olun.

  • 403 Forbidden, kullanıcının istenen kaynak için izni olmadığını belirtir.

    • Kullanıcıya gerekli izinleri verildiğinden emin olun (ör. kullanıcıya dosya tabanlı bir istekte bir dosyaya erişim izni verme).

  • 404 Not Found, istenen kaynağın mevcut olmadığı anlamına gelir.

    • API uç noktası için kullanılan URL'nin doğru olduğundan emin olun.
    • Bir kaynak getiriyorsanız başvuruda bulunulan kaynağın var olduğundan emin olun (örneğin, dosya dosya tabanlı bir API'ye yönelikse).

İstekleri inceleyin

API yanıtları isteğin kötü bir şekilde oluşturulduğunu gösterdiğinde (örneğin, 400 durum kodu) isteklerin incelenmesi yararlı olur. İsteklerin incelenmesine yardımcı olmak için UrlFetchApp, fetch() yöntemi için getRequest() adlı tamamlayıcı bir yönteme sahiptir.

Bu yöntem, sunucuya bir istek göndermek yerine gönderilecek 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 istek öğelerini inceleyebilir.

Örneğin, isteğinizdeki form verileri bir araya getirilmiş çok sayıda 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.

İstek ve yanıtları günlüğe kaydet

Bir üçüncü taraf API'ye gelen istekleri ve yanıtları inceleme sürecinin tamamına yardımcı olmak amacıyla aşağıdaki yardımcı işlev, hem isteklerin hem de yanıtların günlüğe kaydedilmesi için UrlFetchApp.fetch() yerine geçici olarak 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ı çalıştırırken tüm isteklerin ve yanıtların ayrıntıları konsola kaydedilir. Böylece hata ayıklama kolaylaşır.