Gelişmiş Google hizmetleri

Apps Script'teki gelişmiş hizmetler, belirli genel Google API'lerine HTTP arayüzlerini kullanmaktan daha az kurulumla bağlanmanıza olanak tanır. Gelişmiş hizmetler, bu Google API'leri için ince sarmalayıcılardır. Bu kitaplıklar, Apps Komut Dosyası'nın yerleşik hizmetlerine benzer şekilde çalışır. Örneğin, otomatik tamamlama özelliği sunar ve Apps Komut Dosyası, yetkilendirme akışını otomatik olarak yönetir. Ancak komut dosyasında kullanabilmek için gelişmiş bir hizmeti etkinleştirmeniz gerekir.

Gelişmiş hizmetleri etkinleştirme

Gelişmiş bir Google hizmetini kullanmak için aşağıdaki talimatları uygulayın:

1. adım: Gelişmiş hizmeti etkinleştirin

Apps Komut Dosyası Düzenleyicisi'ni kullanarak veya manifesti düzenleyerek gelişmiş bir hizmeti etkinleştirebilirsiniz.

A yöntemi: Düzenleyiciyi kullanma

  1. Apps Komut Dosyası projesini açın.
  2. Sol tarafta Düzenleyici'yi tıklayın.
  3. Sol tarafta, Hizmetler'in yanındaki Hizmet ekle'yi tıklayın.
  4. Gelişmiş bir Google hizmeti seçin ve Ekle'yi tıklayın.

2. yöntem: Manifest dosyasını kullanma

Manifest dosyasını düzenleyerek gelişmiş hizmetleri etkinleştirebilirsiniz. Örneğin, Google Drive gelişmiş hizmetini etkinleştirmek için enabledAdvancedServices alanını dependencies nesnesine ekleyin:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

Etkinleştirdiğiniz gelişmiş hizmetler, otomatik tamamlama özelliğinde kullanılabilir.

2. adım: Google Cloud API'yi etkinleştirin (yalnızca standart Google Cloud projesi projeleri)

Varsayılan bir Google Cloud projesi (Apps Komut Dosyası tarafından otomatik olarak oluşturulur) kullanıyorsanız bu adımı atlayabilirsiniz. API, 1. adımda hizmeti eklediğinizde otomatik olarak etkinleştirilir.

Standart bir Google Cloud projesi kullanıyorsanız gelişmiş hizmete karşılık gelen API'yi de manuel olarak etkinleştirmeniz gerekir. API'yi manuel olarak etkinleştirmek için:

  1. **Google Cloud Console**'da komut dosyanızla ilişkili Cloud projesini açın.

  2. Konsolun üst kısmındaki arama çubuğunu tıklayın ve API'nin adının bir bölümünü (örneğin, "Takvim") yazın. Ardından, adı gördüğünüzde bir kez tıklayın.

  3. Enable API'ı (API'yi etkinleştir) tıklayın.

  4. Google Cloud Console'u kapatın ve komut dosyası düzenleyiciye dönün.

Yöntem imzaları nasıl belirlenir?

Gelişmiş hizmetler genellikle aynı nesneleri, yöntem adlarını ve parametreleri kullanır. Yöntem imzaları, Apps Komut Dosyası'nda kullanılmak üzere çevrilir. Komut dosyası düzenleyicinin otomatik tamamlama işlevi genellikle başlamak için yeterli bilgiyi sağlar. Ancak aşağıdaki kurallar, Apps Komut Dosyası'nın herkese açık bir Google API'sinden nasıl yöntem imzası oluşturduğunu açıklar.

Google API'lerine yapılan istekler; yol parametreleri, sorgu parametreleri, istek gövdesi veya medya yükleme eki gibi çeşitli veri türlerini kabul edebilir. Bazı gelişmiş hizmetler, belirli HTTP isteği başlıklarını da kabul edebilir (örneğin, Takvim gelişmiş hizmeti).

Google Apps Komut Dosyası'ndaki ilgili yöntem imzası aşağıdaki bağımsız değişkenlere sahiptir:

  1. İstek metni (genellikle bir kaynak), JavaScript nesnesi olarak.
  2. Yol veya gerekli parametreler, ayrı ayrı bağımsız değişkenler olarak. Yöntem birden fazla yol parametresi gerektiriyorsa bunlar API uç noktası URL'sinde listelendikleri sırayla görünür.
  3. Medya yükleme ekini Blob bağımsız değişkeni olarak kullanın.
  4. Parametre adlarını değerlerle eşleyen bir JavaScript nesnesi olarak isteğe bağlı parametreler (genellikle sorgu parametreleri).
  5. HTTP istek üstbilgileri, üstbilgi adlarını üstbilgi değerleriyle eşleyen bir JavaScript nesnesi olarak.

Yöntemde belirli bir kategoride öğe yoksa imzanın bu kısmı atlanır.

Bilmeniz gereken bazı özel istisnalar vardır:

  • Medya yüklemeyi kabul eden yöntemler için uploadType parametresi otomatik olarak ayarlanır.
  • Google API'deki delete adlı yöntemler, JavaScript'te delete ayrılmış bir kelime olduğundan Apps Komut Dosyası'nda remove olarak adlandırılır.
  • Gelişmiş bir hizmet HTTP istek başlıklarını kabul edecek şekilde yapılandırılmışsa ve bir istek başlıkları JavaScript nesnesi ayarlarsanız isteğe bağlı parametreler JavaScript nesnesini de ayarlamanız gerekir (isteğe bağlı parametreleri kullanmıyorsanız boş bir nesneye ayarlayın).

Örnek: Calendar.Events.insert

Takvim etkinliği oluşturmak istediğinizi varsayalım. Google Calendar API dokümanlarında ilgili HTTP isteği yapısı gösterilmektedir:

  • HTTP Fiili: POST
  • İstek URL'si: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

  • İstek Metni: Event resource.

  • Sorgu parametreleri: sendUpdates, supportsAttachments vb.

Apps Komut Dosyası'nda yöntem imzası, bu girişlerin yeniden sıralanmasıyla belirlenir:

  1. Body: Etkinlik kaynağı (JavaScript nesnesi).
  2. Yol: calendarId (dize).
  3. İsteğe bağlı parametreler: Sorgu parametreleri (JavaScript nesnesi).

Elde edilen yöntem çağrısı şu şekilde görünür:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

Gelişmiş hizmetler mi yoksa HTTP mi?

Gelişmiş Google hizmetlerinin her biri herkese açık bir Google API'siyle ilişkilendirilir. Apps Komut Dosyası'nda bu API'lere gelişmiş hizmetleri kullanarak veya UrlFetch ile doğrudan API istekleri göndererek erişebilirsiniz.

Gelişmiş hizmet yöntemini kullanıyorsanız Apps Komut Dosyası, yetkilendirme akışını yönetir ve otomatik tamamlama desteği sunar. Ancak, bu hizmeti kullanabilmek için gelişmiş hizmeti etkinleştirmeniz gerekir.

API'ye doğrudan erişmek için UrlFetch yöntemini kullanıyorsanız Google API'yi harici bir API olarak değerlendiriyorsunuz demektir. Bu yöntemle API'nin tüm yönleri kullanılabilir. Ancak API yetkilendirmesini sizin yapmanız gerekir.

Aşağıdaki tabloda iki yöntem karşılaştırılmaktadır:

Özellik Gelişmiş Hizmet UrlFetch (HTTP)
Yetkilendirme Otomatik olarak işlenir Manuel işlem yapılması gerekiyor
Otomatik tamamlama Kullanılabilir Kullanılamıyor
İşlevsellik Kapsamı API'nin bir alt kümesi olabilir. Tüm API özelliklerine tam erişim
Karmaşıklık Daha kolay Daha karmaşık (başlık oluşturma ve yanıt ayrıştırma gerektirir)

Kod karşılaştırması

Kod örnekleri, UrlFetchApp kullanarak Takvim etkinliği oluşturma ile gelişmiş hizmeti kullanarak Takvim etkinliği oluşturma arasındaki karmaşıklık farkını gösterir.

Gelişmiş Hizmet:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

Mümkün olduğunda gelişmiş bir hizmet kullanmanızı, UrlFetch yöntemini ise yalnızca gelişmiş hizmetin kullanılamadığı veya ihtiyacınız olan işlevleri sağlamadığı durumlarda kullanmanızı öneririz.

Gelişmiş hizmetler için destek

Gelişmiş hizmetler, Google API'leri için ince sarmalayıcılar olduğundan, bunları kullanırken karşılaşılan sorunlar genellikle Apps Komut Dosyası ile değil, temel API ile ilgili sorunlardır.

Gelişmiş bir hizmeti kullanırken sorunla karşılaşırsanız temel API'nin destek talimatları kullanılarak bildirilmelidir.