Üçüncü Taraf API'ler

Google Ads komut dosyalarının güçlü bir özelliği, verilerle entegre etme olanağıdır. ve üçüncü taraf API'lerinden hizmetler satın alabilirsiniz.

Bu kılavuzda, komut dosyası yazmanıza yardımcı olacak aşağıdaki kavramlar diğer hizmetlere bağlan:

  • HTTP istekleri yapma: Nasıl kullanılır? Erişmek için UrlFetchApp harici API'ler.
  • Kimlik Doğrulama: Burada, sık karşılaşılan bazı kimlik doğrulama senaryolarını ele alıyoruz.
  • Ayrıştırma yanıtları: Döndürülen JSON ve XML verilerinin nasıl işleneceği.

Ayrıca bir sayıya ait örnekler yaygın olarak kullanılan API'lere bakalım.

UrlFetchApp ile veri getirme

UrlFetchApp şunları sağlar: üçüncü taraf API'leriyle etkileşime geçmek için gerekli temel işlevler

Aşağıdaki örnekte, OpenWeatherMap'ı açın. OpenWeathermap'i seçmemizin sebebi oldukça basit bir yetkilendirme şeması ve API'sidir.

İstekte bulunun

OpenWeathermap dokümanları geçerli hava durumunu isteme biçimi şu şekildedir:

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

URL, ilk yetkilendirme örneğimizi sağlar: apikey parametresi gerekir ve değer her kullanıcı için benzersizdir. Bu anahtar, kaydolma.

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 kod çalıştırıldığında uzun bir JSON dizesi ortaya çıkar Google Ads komut dosyalarında günlük kaydı penceresine yazılan metin.

Sonraki adım, bunu hesabınızda kullanılabilecek bir biçime dönüştürmektir. komut dosyası.

JSON verileri

Birçok API, yanıtları JSON biçiminde sağlar. Bu durum, basit bir JavaScript nesnelerinin serileştirilmesi (örneğin, nesneler, diziler ve temel türler) dize olarak temsil edilebilir ve aktarılabilir.

Bir JSON dizesini (ör. OpenWeatherMap: JavaScript nesnesine geri dönün ve JSON.parse yöntemini çağırı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 özelliği olan bir nesneye dönüştürür. name.

Şu konuyla ilgili daha fazla bilgi için Yanıtları ayrıştırma bölümüne bakın: farklı formatlardaki API yanıtlarıyla çalışma.

Hata işleme

Hata işleme, üçüncü taraf API'leriyle çalışırken dikkat edilmesi gereken önemli bir konudur çünkü üçüncü taraf API'leri genellikle sık sık değiştiğinden ve beklenmedik yanıt değerleri, örneğin:

  • API'nin URL'si veya parametreleri bilginiz olmadan değiştirilebilir.
  • API anahtarınızın (veya diğer kullanıcı kimlik bilgilerinin) süresi dolabilir.
  • Yanıtın biçimi, bildirimde bulunulmadan değiştirilebilir.

HTTP durum kodları

Beklenmeyen yanıt olasılığı nedeniyle HTTP durum kodu kullanabilir. Varsayılan olarak Bir HTTP hata koduyla karşılaşılırsa UrlFetchApp istisna oluşturur. Alıcı: Bu davranışı değiştirdiğinizde, şu örneği inceleyin:

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ı

Geliştiriciler, üçüncü taraf API'leri değiştiğinden çoğu zaman veya kontrol edebiliyorlar. Örneğin, name özelliği OpenWeathermap örneğinde döndürülen sonuç locationName olarak değiştirildiğinde komut dosyaları başarısız olur.

Bu nedenle, döndürülen yapının beklendiği gibi, ö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 giriş örneği yalnızca veri getirmesi gerekir. Genellikle, uzaktan kumandada durum değişmeyen API çağrıları HTTP GET bağlantısını kullanma yöntemidir.

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

POST çağrılarını UrlFetchApp ile göstermek için aşağıdaki örnek Slack ile entegrasyonu gösterir. Slack uygulamasını kullanarak Slack kullanıcılarına ve gruplarına Slack mesajı gönderebilirsiniz.

Slack'i kurma

Bu kılavuzda, bir Slack hesabına daha önce kaydolduğunuz varsayılır.

Önceki örnekte verilen OpenWeatherMap'te olduğu gibi, jeton. Slack benzersiz bir URL kullanarak Ekibinize, Gelen Webhook adı verilen iletiler gönderebilir.

Gelen Webhook'u oluşturun Gelen Web Kancaları Entegrasyonunu ekleyin ve talimatları uygulayın. İlgili içeriği oluşturmak için kullanılan mesaj için kullanılacak bir URL yayınlamalıdır.

POST isteği gönderme

Gelen Webhook'unuzu oluşturduktan sonra POST isteğinde bulunmak için options UrlFetchApp.fetch:

  • method: Belirtildiği gibi, bu varsayılan olarak GET değerine ayarlanır, ancak burada bunu geçersiz kılar ve POST olarak ayarla.

  • payload: POST kapsamında sunucuya gönderilecek verilerdir. isteği gönderin. Bu örnekte Slack, bir nesnenin JSON biçiminde serileştirilmesini bekliyor olduğu gibi, Slack dokümanlarına göz atın. 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 iletilerin etkinleştirilmesi için gereken minimum süre gösterilmektedir. genişletilmiş örnek, bir Kampanya Performansı'nın oluşturulması ve gönderilmesi Bir kullanıcıya bildirin bazı biçimlendirme ve görüntüleme seçeneklerini göreceksiniz.

Gelen mesaj

Slack'teki ileti biçimlendirmesine bakın dokümanlarına göz atabilirsiniz.

Form verileri

Yukarıdaki örnekte, payload özelliği olarak bir JSON dizesinin kullanıldığı gösterilmektedir (POST isteği için)

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

  • payload bir dize olduğunda, dize bağımsız değişkeni başlık ekleyin.

  • payload bir nesne olduğunda, örneğin bir değer eşlemesi olduğunda:

    {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ığı şu şekilde ayarlandı: application/x-www-form-urlencoded.

Bazı API'ler, POST istekleri gönderilirken form verilerinin kullanılmasını gerektirir. Dolayısıyla bu JavaScript nesnelerinden form verilerine otomatik dönüştürme, göz önünde bulundurun.

HTTP temel kimlik doğrulaması

HTTP temel kimlik doğrulama, birçok API tarafından kullanılır.

Kimlik doğrulama, Her istekteki HTTP üstbilgileri.

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 bir iki nokta üst üste, örneğin username:password.
  2. Base64, parolayı kodlar. Örneğin username:password şöyle olur: dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. İsteğe Authorization: Basic <encoded passphrase> biçiminde bir Authorization başlığı 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ü, HTTP Temel Kimlik Doğrulaması'nı kullanmayı gösteren iki örnek içerir:

Plivo

Plivo, yüksek kaliteli ileti gönderme ve API'leri aracılığıyla SMS mesajları alarak Bu örnekte, mesaj.

  1. Plivo'ya kaydolun.
  2. Örnek komut dosyasını şuraya yapıştırın: komut dosyası oluşturabilirsiniz.
  3. PLIVO_ACCOUNT_AUTHID ve PLIVO_ACCOUNT_AUTHTOKEN değerlerini değerlerini yönetim kontrol panelinde bulabilirsiniz.
  4. ile ilgili bildirim için e-posta adresinizi komut dosyasında belirtildiği gibi ekleyin: hatalar.
  5. Plivo'yu kullanmak için numara satın almanız veya denemeye numara eklemeniz gerekir hesap. Şunları yapabilecek Korumalı Alan numaraları ekleyin deneme hesabıyla birlikte kullanılması gerekir.
  6. Hem gönderen olarak görünecek numarayı hem de alıcıyı ekleyin sayı.
  7. Komut dosyasındaki PLIVO_SRC_PHONE_NUMBER değerini, korumalı alan numaralarından biriyle güncelleyin yeni bir kayıt başladı. Bu, Birleşik Krallık numarası için 447777123456 örneği.

Twilio

Twilio, ileti ve veri alışverişi API'leri aracılığıyla SMS mesajları alarak Bu örnekte, mesaj.

  1. Twillio'ya kaydolun.
  2. Örnek komut dosyasını yapıştırın komut dosyasına dönüştürmeyi öğreneceksiniz.
  3. TWILIO_ACCOUNT_SID ve TWILIO_ACCOUNT_AUTHTOKEN değerlerini değerlerinin hesap konsolu sayfasında gösterilmesidir.
  4. TWILIO_SRC_PHONE_NUMBER yerine kontrol paneli: Bu, numaraya Twilio tarafından ileti gönderilmesine izin verildi.

OAuth 1.0

Popüler hizmetlerin çoğu, kimlik doğrulama için OAuth kullanır. OAuth pek çok farklı sektörde aroma ve versiyonları var.

HTTP temel kimlik doğrulamasında ise kullanıcı tek bir kullanıcı adı ve şifresi olduğundan OAuth, üçüncü taraf uygulamalarının kullanıcıya özel kimlik bilgileri kullanılarak kullanıcının hesabına ve verilerine erişim izni verildi üçüncü taraf uygulamasıdır. Ayrıca, erişim düzeyi söz konusu uygulamaya özgüdür.

OAuth 1.0 arka planı için OAuth Core kılavuzuna göz atın. Özellikle bkz. 6. OAuth ile kimlik doğrulama. Tam üç ayaklı OAuth 1.0 için işlem aşağıdaki gibidir:

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

Üçüncü taraf hizmetlerin OAuth 1.0'ı kullanıcı etkileşimi olmadan kullanması için (örneğin, için 1, 2 ve 3 numaralı adımların uygulanması mümkün değildir. Bu nedenle, bazı hizmetler kendi yapılandırmalarından bir erişim jetonu yayınlar konsolunu kullanarak uygulamanın doğrudan 4. adıma geçmesine izin verin. Bu, tek ayaklı OAuth 1.0'dır.

OAuth1

Google Ads komut dosyalarında OAuth 1.0

Google Ads komut dosyalarında, her komut dosyası genellikle bir uygulama olarak yorumlanır. Hizmete ilişkin konsol/yönetim ayarları sayfasından bu genellikle gerekli olan bazı araçlar:

  • Komut dosyasını temsil edecek bir uygulama yapılandırması oluşturun.
  • Komut dosyasına hangi izinlerin genişletileceğini belirtin.
  • Kullanım için Tüketici anahtarı, Tüketici sırrı, erişim jetonu ve erişim sırrı edinme her şeyi öğreteceğim.

OAuth 2.0

OAuth 2.0, popüler API'lerde aşağıdakilere erişim sağlamak için kullanılır: kullanıcı verileri. Belirli bir üçüncü taraf hizmeti için hesabın sahibi kullanıcı verilerine erişmelerine olanak sağlamak için belirli uygulamalara erişim izni vermelidir. İlgili içeriği oluşturmak için kullanılan avantajı, sahibinin:

  • Hesap kimlik bilgilerini uygulamayla paylaşması gerekmez.
  • Verilere hangi uygulamaların bağımsız olarak erişebileceğini ve ne ölçüde. (Örneğin, verilen erişim salt okunur olabilir veya veri alt kümesi olabilir.)

Google Ads komut dosyalarında OAuth 2.0 özellikli hizmetleri kullanmak için aşağıdaki yöntemlerden yararlanabilirsiniz: için şu adımları izleyin:

Komut dosyanızın dışında

Google Ads Komut Dosyaları'na üçüncü taraf API. Çoğu durumda bu, bir proje yöneticisinin uygulamasını kullandığınızdan emin olun. Bu uygulama Google Ads komut dosyanızı temsil eder.

Google Ads Komut Dosyası uygulamasının hangi erişim haklarına sahip olması gerektiğini siz belirlersiniz. verilir ve buna genellikle bir istemci kimliği atanır. Böylece proje boyunca OAuth 2, belirli bir sürümde hangi uygulamaların verilerinize erişimi olduğunu kontrol etmek için ve ayrıca verilerin hangi özelliklerini görebileceklerini ya da değiştirebilirsiniz.

Komut dosyanızda

Uzak sunucuyla yetkilendir. İzin türüne bağlı olarak sunucu tarafından izin verilmişse akış olarak bilinen farklı bir ancak tüm bunlar sonuçta bir erişim jetonunun bu oturumda sonraki istekler için kullanılır.

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

Yetkilendirme akışları

Her hibe türü ve ilgili akış, farklı kullanım senaryolarına hitap eder. Örneğin, Örneğin, kullanıcı etkileşimli bir oturuma katılırken farklı bir akış kullanılır. uygulamasında çalışması gereken bir senaryonun aksine, arka planda çalışmaya devam edebilir.

API sağlayıcılar hangi izin türlerini kabul edeceklerine karar verir ve bu durum, Kullanıcının API entegrasyonunda nasıl ilerlediği.

Uygulama

Farklı OAuth akışlarının tümü için amaçlanan erişim jetonu almaktır. Ardından isteklerin kimliğini doğrulamak amacıyla oturumun geri kalanında kullanılabilir.

Örnek kitaplık , her farklı akış türü için kimlik doğrulamasının nasıl yapılacağını gösterir. Bunların her biri Yöntemleri, erişim jetonunu alan ve depolayan bir nesne döndürür ve kimliği doğrulanmış istekleri kolaylaştı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 verilir

İstemci kimlik bilgileri izni: uygulamanın, yeni bir OAuth2 akışı biçimi olduğu için Bir Sınırlı süreli erişim jetonu.

İ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 bilgisi verme işlemine benzer çünkü sunucuya gönderilen basit bir istek, kullanılabilecek bir erişim jetonu döndürür ele alacağız.

Yenileme jetonu

Yenileme jetonu alma

Yenileme jetonu verilmesiyle ilgili fark, ayrıntıların istemci kimlik bilgileri izninin uygulama yapılandırmasından gelmesi için gerekir (örneğin, hizmetin kontrol panelinde) yenileme jetonu verilir yetkilendirme kodu gibi daha karmaşık bir akışın parçası olarak izin ver; bu işlem, etkileşim:

Yetkilendirme kodu

Yenileme jetonu almak için OAuth Playground'u kullanma

OAuth2 oyun alanı, kullanıcının gerçekleştirmesine izin veren bir kullanıcı arayüzü sunar. .

Sağ üstteki ayarlar düğmesi, tüm parametreleri tanımlamanıza olanak sağlar OAuth akışında kullanılacak filtre seçenekleri:

  • 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 birlikte kullanılır.
  • client ID and secret (İstemci kimliği ve gizli anahtar): Uygulamanın kimlik bilgileri.

OAuth Oyun Alanı

Yenileme jetonu almak için komut dosyası kullanma

Akışı tamamlamak yerine komut dosyası tabanlı bir alternatifi yenileme jetonu nesil örneklem.

Jeton kullanımını yenile

İlk yetkilendirme yapıldıktan sonra hizmetler yenileme yapabilir bu kimlik, istemci kimlik bilgileri akışına benzer şekilde kullanılabilir. 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ı raporu ekleyin. Arama Ağı Reklamlarına Diğer işlemlerin tüm ayrıntıları için 360 API referansı bir yöntem de vardır.

Komut dosyasını oluşturun
  1. API Konsolu'nda yeni bir proje oluşturun. ve aşağıdaki adımları izleyerek bir istemci kimliği, istemci gizli anahtarı ve yenileme jetonu edinin: lütfen deneyin, DoubleClick Search API'yi etkinleştirdiğinizden emin olun.
  2. Örneği yapıştırın komut dosyasını komut dosyası oluşturun.
  3. Örnek OAuth2 etiketini yapıştırın kitaplığının altındaki daha fazla bilgi edineceksiniz.
  4. Komut dosyasını, istemci kimliği, istemci gizli anahtarı ve gizli anahtar değerleri için doğru değerleri içerecek şekilde değiştirin. ve yenileme jetonu.

Apps Komut Dosyası Yürütme API'si örneği

Bu örnekte, Apps Komut Dosyası'nda Komut Dosyası Yürütme API'si. Bu işlem, Apps Komut Dosyası'nın Google Ads komut dosyalarından çağrılmalıdır.

Apps Komut Dosyası oluşturma

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

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
  3. API Konsolu'na gitmek için proje adını tıklayın.
  4. API'ler ve Hizmetler.
  5. Uygun API'leri etkinleştirin. Bu örnekte, Drive API ve Uygulamalar Komut Dosyası Yürütme API.
  6. Menüdeki Credentials (Kimlik bilgileri) öğesinden OAuth kimlik bilgilerini oluşturun.
  7. Komut dosyanıza dönüp, komut dosyasını Yayınla > API Yürütülebilir olarak dağıtın.
Google Ads komut dosyasını oluşturma
  1. Örneği yapıştırın komut dosyasını komut dosyası oluşturabilirsiniz.
  2. Ayrıca, örnek OAuth2 etiketini yapıştırın. kitaplığının altındaki daha fazla bilgi edineceksiniz.
  3. Komut dosyasını, istemci kimliği, istemci gizli anahtarı ve gizli anahtar değerleri için doğru değerleri içerecek şekilde değiştirin. ve yenileme jetonu.

Hizmet hesapları

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

Hizmet hesapları, kullanıcılara erişmek için kullanılmadıklarından yukarıdakilerden farklıdır. veriler: Kimlik doğrulama sonrasında, istekler adına Hizmet Hesabı tarafından yapılır. projenin sahibi olan kullanıcı olarak değil, Örneğin, dosya oluşturmak için Drive API'yi kullanması gerektiğini belirten hizmet hesabına ait olduğunu ve varsayılan olarak projenin sahibidir.

Google Natural Language API örneği

natural language API, duyarlılık ve analiz varlık analizi.

Bu örnekte, duyarlılık (başlık veya açıklama dahil) kullanın. Bu sayede, hedeflerinize ulaşmak için mesajının ne kadar olumlu olduğuna ve büyüklüğüne Pasta satıyoruz veya Londra'nın en iyi pastalarını satıyoruz. Hemen alın!

Komut dosyasını ayarlama
  1. API Konsolu'nda yeni bir proje oluşturun
  2. Doğal Dil'i etkinleştirin. API
  3. Proje için faturalandırmayı etkinleştirin.
  4. Hizmet Oluşturma Hesap. Kimlik bilgileri JSON dosyasını indirin.
  5. Örneği yapıştırın komut dosyasını yeni bir komut dosyası oluşturun.
  6. Ayrıca, örnek OAuth2 etiketini yapıştırın. kitaplığının altındaki daha fazla bilgi edineceksiniz.
  7. Gerekli değerleri değiştirin:
    • serviceAccount: Hizmet hesabının e-posta adresi (ör. xxxxx@yyyy.iam.gserviceaccount.com.
    • key: Hizmet oluşturulurken indirilen JSON dosyasındaki anahtar. Hesap'a dokunun. -----BEGIN PRIVATE KEY... tarihinde başlayıp ...END PRIVATE KEY-----\n tarihinde sona erecek.

API yanıtları

API'ler çeşitli biçimlerde veri döndürebilir. Bunlardan en önemlileri XML ve JSON olur.

JSON

JSON genellikle XML'den daha basittir ve yanıt formatını kullanın. Ancak yine de bazı sorunlar ortaya çıkabilir.

Yanıt doğrulaması

API'ye yapılan çağrıdan başarılı bir yanıt almanız, normal şartlarda sonraki adım, JSON dizesini JavaScript'e dönüştürmek için JSON.parse kullanmaktır nesnesini tanımlayın. Bu noktada, ayrıştırılan ürünün daha büyük bir kısmının ayrıştırıldığı başarısız sonuçlar:

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üz altında değilse, yanıt değişebilir ve özellikler artık mevcut olmayabilir:

// 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ıt kodu ile ayrıştırılabilir XmlService parse yöntem:

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

XmlService.parse, XML'deki hataları tespit edip istisnalar bildirirken uyumlu olmadığı takdirde, XML'i belirli bir şema.

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öntemini kullanarak:

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ı almak amacıyla kullanılır. XML yanıtı şu 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, gerekli olan bazı araçlar:

  • Belgeden ad alanı özelliğini çıkarın.
  • Alt öğelere geçiş yaparken ve bu öğelere erişirken bu ad alanını kullanın.

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

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 örneğe bakalım:

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

Özellikler alınabilir. Örneğin:

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

Bir öğede bulunan metin getText() kullanılarak okunabilir, ancak bu bir öğenin birden fazla metin alt öğesi olduğunda birleştirilemez. Dikkatlice birden fazla alt öğe varsa getChildren() kullanılarak ve her bir alt öğe için yinelenerek gibi metinlerdir.

Sportradar örneği

Bu Sportradar'ın tamamı example ile ilgili açıklama futbol maçlarının ayrıntılarını, özellikle de İngiltere Premier Ligi'ni alma şununla eşleşir: Soccer API Sportradar tarafından sunulan çok sayıda spor feed'inden 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 alamaz. Her biri Oluşturduğunuz uygulamayla ilişkili farklı sporlar olabilir ve kullanabilirsiniz.

  1. Uygulamalar bölümünde Yeni uygulama oluştur'u tıklayın. Başvuruyu verin bir ad ve açıklama girin ve web sitesi alanını dikkate almayın.
  2. Yalnızca Futbol Denemesi Avrupa v2 için yeni anahtar ver'i seçin.
  3. Uygulamayı 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ı yapıştırın komut dosyasına dönüştürmeyi öğreneceksiniz.
  2. Girişteki API anahtarını yukarıda alınan anahtarla değiştirin ve e-posta adresi alanı

Sorun giderme

Üçüncü taraf API'lerle çalışırken, hatalar çeşitli nedenlerle ortaya çıkabilir: örnek:

  • Sunucuya, API'nin beklemediği bir biçimde istek gönderen istemciler.
  • Müşteriler, karşılaşılan yanıt biçiminden farklı bir yanıt biçimi beklemektedir.
  • Geçersiz jeton veya anahtarlar kullanan istemciler ya da yer tutucu olarak kalan değerler.
  • Kullanım sınırlarına ulaşan istemciler.
  • Geçersiz parametreler sağlayan istemciler.

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

Yanıtları ayrıştır

Varsayılan olarak, hata döndüren tüm yanıtlar (durum kod 400 veya üzeriyse) Google Ads komut dosyaları motoru tarafından atılabilir.

Bu davranışı önlemek ve hata ile hata mesajının sisteme isteğe bağlı parametrelerin muteHttpExceptions özelliğini şuna ayarlayın: UrlFetchApp.fetch. Ö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ılı olduğunu gösterir. Yanıt beklenen şunları göz önünde bulundurun:

    • Bazı API'ler hangi alanların ve/veya yanıt biçiminin pek de iyi olmadığını unutmayın. Bu konuyla ilgili ayrıntılar için API dokümanlarını inceleyin.
    • Bir API'nin çağrılabilecek birden fazla kaynağı olabilir. Destek için: farklı bir kaynağın daha iyi olup olmadığını ve ihtiyacınız olan verileri döndürecektir.
    • Kod yazıldıktan sonra API değişmiş olabilir. Destek için: geliştiriciden kontrol edin.

  • 400 Bad Request genellikle sunucuya gönderilen isteğin biçimlendirmesi veya yapısı. Şunu inceleyin: API spesifikasyonlarıyla karşılaştırıp API spesifikasyonlarına uygun olduğundan emin olmak için emin olmanız gerekir. Aşağıdakilerle ilgili ayrıntılar için İstekleri inceleme bölümüne bakın: inceleme konusunu işleyeceğiz.

  • 401 Unauthorized genellikle API'nin yardımcı olur.

    • API temel yetkilendirme kullanıyorsa Authorization üstbilgisinin oluşturulmakta ve sağlanıyordur.
    • API, OAuth 2.0 kullanıyorsa erişim jetonunun alındığından emin olun ve hamiline ait jeton olarak sağlanıyorsa.
    • Yetkilendirmeyle ilgili diğer tüm varyasyonlar için, istek için kimlik bilgileri sağlanıyor.

  • 403 Forbidden, kullanıcının kaynak için izni olmadığını gösterir emin olun.

    • Kullanıcıya gerekli izinlerin verildiğinden emin olun. Örneğin, Kullanıcı, dosya tabanlı bir istekte dosyaya erişim izni verebilir.

  • 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şvurulan kaynağın mevcut olduğundan emin olun (örneğin, dosya, dosya tabanlı bir API için mevcutsa).

İstekleri inceleme

API yanıtları isteğin kötü olduğunu belirttiğinde istekleri incelemek yararlı olur bir 400 durum kodu olabilir. Taleplerin incelenmesine yardımcı olmak için UrlFetchApp fetch() yöntemi için getRequest()

Bu yöntem, sunucuya istek göndermek yerine isteği oluşturur gönderilmiş olan bir e-posta alırsınız ve ardından dosyayı geri döndürür. Bu, kullanıcıya İsteğin doğru göründüğünden emin olmak için istek öğelerini inceleyin.

Örneğin, isteğinizdeki form verileri birleştirilmiş çok sayıda dizeden oluşuyorsa bu formu oluşturmak için oluşturduğunuz fonksiyonda hata olabilir. dışı verilerdir. En basit şekilde:

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

istek öğelerini incelemenize olanak tanır.

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

Talepleri ve yanıtları inceleme sürecinin tamamında yardımcı olmak için üçüncü taraf API'sini kullanıyorsanız aşağıdaki yardımcı işlev, hem istekleri hem de yanıtları günlüğe kaydetmek için UrlFetchApp.fetch() öğesinin yerine geçer.

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

  2. Aşağıdaki işlevi komut dosyanızın sonuna 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ürken tüm isteklerin ve yanıtların ayrıntıları şuraya kaydedilir: hata ayıklamayı kolaylaştırabilir.