Hizmet hesaplarını kullanarak Apps Komut Dosyası projesi olarak kimlik doğrulama

Bu kılavuzda, Apps Komut Dosyası'nda API'leri çağırırken hizmet hesabıyla nasıl kimlik doğrulanacağı açıklanmaktadır.

Hizmet hesabı, bir kişi yerine bir uygulama tarafından kullanılan özel bir hesap türüdür. Verilere erişmek veya robot hesabı tarafından işlemleri gerçekleştirmek ya da Google Workspace veya Cloud Identity kullanıcıları adına verilere erişmek için hizmet hesabı kullanabilirsiniz. Daha fazla bilgi için Hizmet hesaplarını anlama başlıklı makaleyi inceleyin.

Google Workspace API'leri için kimlik doğrulama hakkında genel bilgi edinmek istiyorsanız Erişim kimlik bilgileri oluşturma başlıklı makaleyi inceleyin.

Apps Komut Dosyası'nda hizmet hesapları ne zaman kullanılır?

ScriptApp.getOAuthToken() gibi diğer kimlik doğrulama yöntemleri yerine hizmet hesabı kimlik doğrulamasını kullanmayı tercih edebileceğiniz bazı nedenleri aşağıda bulabilirsiniz:

• Google Cloud API'leri ve hizmetleriyle daha iyi performans: Birçok Google Cloud API'si, hizmet hesabı kimlik doğrulaması için tasarlanmıştır. Hizmet hesapları, çoğu API ile etkileşim kurmak için daha entegre, güvenilir ve güvenli bir yol da sağlayabilir.
• Ayrılmış izinler: Hizmet hesaplarının, kullanıcılardan ayrı kendi izinleri vardır. Apps Komut Dosyası projesini diğer kullanıcılarla paylaştığınızda ScriptApp.getOAuthToken() kimlik doğrulama yöntemi başarısız olabilir. Hizmet hesaplarını kullanarak komut dosyalarını paylaşabilir ve Google Workspace eklentileri olarak yayınlayabilirsiniz.
• Otomatik komut dosyaları ve uzun süren görevler: Hizmet hesapları, kullanıcı girişi olmadan otomatik komut dosyaları, toplu işlemler veya arka plan görevleri çalıştırmanıza olanak tanır.
• Gelişmiş güvenlik ve en az ayrıcalık ilkesi: Hizmet hesaplarına belirli izinler vererek yalnızca ihtiyaç duydukları kaynaklara erişmelerini sağlayabilirsiniz. Bu, güvenlik risklerini azaltan en az ayrıcalık ilkesine uygundur. ScriptApp.getOAuthToken() kullanmak, komut dosyasına genellikle tüm kullanıcı izinlerini verir. Bu da çok geniş kapsamlı olabilir.
• Merkezi erişim yönetimi: Hizmet hesapları, Google Cloud'un Identity and Access Management (IAM) hizmeti kullanılarak yönetilir. IAM, Google Workspace kuruluşlarının Apps Komut Dosyası projelerindeki kimliği doğrulanmış hizmetlere erişimi yönetmesine yardımcı olabilir.

Ön koşullar

• Bir Google Cloud projesi.
• Cloud projenizde, hizmet hesabı kimlik bilgilerini kullanarak kimlik doğrulaması yapmak istediğiniz API'leri etkinleştirin.
• Hizmet hesaplarına rol atamak için süper yönetici ayrıcalıklarına sahip olmanız gerekir.

Hizmet hesabı oluşturma

Cloud projenizde bir hizmet hesabı oluşturun:

Google Cloud konsolu

1. Google Cloud Console'da Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.

   Hizmet Hesapları'na gitme

2. Hizmet hesabı oluştur'u tıklayın.
3. Hizmet hesabı ayrıntılarını girip Oluştur ve devam et'i tıklayın.
   Not: Google, varsayılan olarak benzersiz bir hizmet hesabı kimliği oluşturur. Kimliği değiştirmek istiyorsanız hizmet hesabı kimliği alanındaki kimliği değiştirin.
4. İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha ayrıntılı bilgi için Kaynaklara erişim verme, erişimi değiştirme ve iptal etme başlıklı makaleyi inceleyin.
5. Devam'ı tıklayın.
6. İsteğe bağlı: Bu hizmet hesabıyla işlemleri yönetebilecek ve gerçekleştirebilecek kullanıcıları veya grupları girin. Daha fazla bilgi için Hizmet hesabı kimliğine bürünmeyi yönetme başlıklı makaleyi inceleyin.
7. Bitti'yi tıklayın. Hizmet hesabının e-posta adresini not edin.

gcloud CLI

1. Hizmet hesabını oluşturun:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha ayrıntılı bilgi için Kaynaklara erişim verme, erişimi değiştirme ve iptal etme başlıklı makaleyi inceleyin.

Hizmet hesabına rol atama

Bir hizmet hesabına, süper yönetici hesabı tarafından önceden oluşturulmuş veya özel bir rol atamanız gerekir.

1. Google Yönetici Konsolu'nda Menü > Hesap > Yönetici rolleri'ne gidin.

   Yönetici rolleri'ne gitme

2. Atamak istediğiniz rolün üzerine gelin ve Yönetici ata'yı tıklayın.

3. Hizmet hesapları ata'yı tıklayın.

4. Hizmet hesabının e-posta adresini girin.

5. Ekle > Rol ata'yı tıklayın.

Hizmet hesabı için kimlik bilgileri oluşturma

Herkese açık/özel anahtar çifti biçiminde kimlik bilgileri almanız gerekir. Bu kimlik bilgileri, uygulamanızdaki hizmet hesabı işlemlerini yetkilendirmek için kodunuz tarafından kullanılır.

Hizmet hesabınızın kimlik bilgilerini almak için:

1. Google Cloud Console'da Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.

   Hizmet Hesapları'na gitme

2. Hizmet hesabınızı seçin.
3. Anahtarlar > Anahtar ekle > Yeni anahtar oluştur'u tıklayın.
4. JSON'ı seçip Oluştur'u tıklayın.

   Yeni herkese açık/özel anahtar çiftiniz oluşturulur ve makinenize yeni bir dosya olarak indirilir. İndirilen JSON dosyasını çalışma dizininize credentials.json olarak kaydedin. Bu dosya, anahtarın tek kopyasıdır. Anahtarınızı güvenli bir şekilde depolama hakkında bilgi edinmek için Hizmet hesabı anahtarlarını yönetme başlıklı makaleyi inceleyin.

5. Kapat'ı tıklayın.

Cloud proje numarasını kopyalayın.

1. Google Cloud Console'da Menü > IAM ve Yönetici �> �Ayarlar'a gidin.

   IAM ve Yönetici Ayarları'na gitme

2. Proje numarası alanındaki değeri kopyalayın.

Apps Komut Dosyası projenizde hizmet hesabı kimlik doğrulamasını ayarlama

Bu bölümde, Cloud projenizdeki hizmet hesabı kimlik bilgilerinizi Apps Komut Dosyası projesine nasıl ekleyeceğiniz açıklanmaktadır.

Apps Komut Dosyası'nda Cloud projenizi ayarlama

1. Bir projeyi açmak veya oluşturmak için Apps Komut Dosyası'na gidin:

   
   Apps Komut Dosyası'nı açın

2. Apps Komut Dosyası projenizde Proje Ayarları'nı tıklayın.

3. Google Cloud Platform (GCP) Projesi bölümünde Projeyi değiştir'i tıklayın.

4. GCP proje numarası bölümüne Google Cloud proje numarasını yapıştırın.

5. Projeyi ayarla'yı tıklayın.

Kimlik bilgilerini komut dosyası özelliği olarak kaydetme

Hizmet hesabı kimlik bilgilerinizi, Apps Komut Dosyası proje ayarlarınıza komut dosyası özelliği olarak kaydederek güvenli bir şekilde saklayın:

1. Önceki bölümde oluşturduğunuz hizmet hesabı JSON dosyanızın (credentials.json) içeriğini kopyalayın.
2. Apps Komut Dosyası projenizde Proje Ayarları'na gidin.
3. Proje Ayarları sayfasında Komut Dosyası Özellikleri'ne gidin ve Komut dosyası özelliği ekle'yi tıklayıp aşağıdakileri girin:
   • Mülk alanına SERVICE_ACCOUNT_KEY girin.
   • Değer alanına JSON anahtar dosyanızın içeriğini yapıştırın.
4. Komut dosyası özelliklerini kaydet'i tıklayın.

OAuth2 kitaplığını ekleyin

OAuth2 kimlik doğrulama akışını işlemek için Apps Komut Dosyası kitaplığı apps-script-oauth2 kullanabilirsiniz.

Kitaplığı Apps Komut Dosyası projenize eklemek için:

1. Apps Komut Dosyası Düzenleyicisi'nde solda, Kitaplıklar'ın yanındaki Kitaplık ekle'yi tıklayın.
2. Komut Dosyası Kimliği alanına 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF girin.
3. Ara'yı tıklayın.
4. En yeni sürümü seçip Ekle'yi tıklayın.

Hizmet hesabı kimlik bilgilerini kullanarak API çağırma

Apps Komut Dosyası projenizdeki hizmet hesabı kimlik bilgilerini kullanmak için aşağıdaki işlevi getServiceAccountService() kullanabilirsiniz:

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

SCOPE kısmını API'yi çağırmak için gereken yetkilendirme kapsamıyla değiştirin. Komut dosyası, önceki adımda SERVICE_ACCOUNT_KEY komut dosyası özelliği olarak kaydettiğiniz hizmet hesabı kimlik bilgilerini kullanır.

Ardından, UrlFetch hizmetiyle ilgili aşağıdaki örnekte gösterildiği gibi bir API'yi çağırmak için bu kimlik bilgilerini kullanabilirsiniz:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

API_URL kısmını çağırdığınız HTTP uç noktasıyla değiştirin.

İlgili konular

• Erişim kimlik bilgileri oluşturma
• Google Chat uygulaması olarak kimlik doğrulama