1. Giriş
Milyarlarca işletme ve kişi, iletişim kurmak ve verileri işlemek için Gmail'i ve diğer G Suite hizmetlerini kullanıyor. Google, bu hizmetlerdeki bilgilere programatik olarak erişmenize yardımcı olmak için G Suite API'leri sunar. Bu API'leri kullanarak günlük iş akışınızı kolayca otomatikleştirebilirsiniz. Bu laboratuvarda, gelen iletilerdeki e-postaları otomatik olarak kategorilere ayıran ve bu kategorileri bir Google E-tablosuna kaydeden güçlü bir Gmail uzantısı oluşturacaksınız. Bu uzantı, G Suite'in RESTful API'lerini, Google Cloud Functions'ı ve diğer Google Cloud Platform hizmetlerini kullanır.
Ne oluşturacaksınız?
Bu laboratuvarda, G Suite API'lerine ve diğer Google Cloud Platform hizmetlerine bağlı birkaç Cloud Functions işlevi oluşturup dağıtacaksınız. Bu işlevler:
- Gmail ve Google E-Tablolar verilerinize güvenli erişim yetkisi verme
- Gelen e-postalara ekli resimleri ayıklama
- Cloud Vision API'yi kullanarak bu görüntüleri kategorilere ayırın.
- Bu kategorileri, gönderenin adresini ve ekin adını bir Google E-Tablosu'na yazın.
Öğrenecekleriniz
- G Suite RESTful API'lerinin temel bilgileri
- Google Cloud Functions ve diğer Google Cloud Platform hizmetlerinin temelleri
- Google Cloud Functions kullanarak Gmail'e programatik olarak erişme
İhtiyacınız olanlar
- Gmail ve Google E-Tablolar erişimi olan bir Google Hesabı. Google Hesabınız yoksa buradan hesap oluşturabilirsiniz.
- JavaScript/Node.js hakkında temel bilgi
2. Öncelikle
API'leri etkinleştirme
Bu laboratuvarda aşağıdaki Google ürünlerini/hizmetlerini kullanacaksınız:
- Google Cloud Functions
- Google Cloud Pub/Sub
- Google Cloud Vision API
- Google Cloud Datastore
- Gmail API
- Google Sheets API
Google Cloud Functions
Google Cloud Functions, Google'ın sunucusuz Hizmet Olarak İşlev platformudur. Bu platform, kod parçacıklarını ("işlevler") basit ve ölçeklenebilir bir şekilde çalıştırmanıza olanak tanır.
Google Cloud Functions'ı etkinleştirmek için ekranınızın sol üst kısmındaki hamburger menüyü tıklayarak soldaki gezinme kenar çubuğunu açın:
Gezinme menüsünde Cloud Functions'ı bulup tıklayın. Projenizde Google Cloud Functions'ı etkinleştirmek için API'yi etkinleştir'i tıklayın.
Google Cloud Pub/Sub
Google Cloud Pub/Sub, veri akışı ve etkinlik teslimi için basit ve ölçeklenebilir bir temeldir. Bu laboratuvarda, Gmail ile Google Cloud Functions arasında kurye görevi görür.
Google Cloud Pub/Sub'ı etkinleştirmek için sol gezinme kenar çubuğunu açın, Pub/Sub'ı bulup tıklayın. Projenizde Google Cloud Pub/Sub'ı etkinleştirmek için API'yi Etkinleştir'i tıklayın.
Google Cloud Datastore
Google Cloud Datastore, ölçeklenebilir ve dağıtılmış bir sunucusuz veritabanıdır.
Google Cloud Datastore'u etkinleştirmek için sol gezinme kenar çubuğunda Datastore'u bulup tıklayın. Yeni sayfada Select Datastore Mode'u (Veri deposu modunu seç) tıklayın.
Bu laboratuvarda herhangi bir veritabanı konumunu kullanabilirsiniz. Google Cloud Datastore'u etkinleştirmek için Veritabanı Oluştur'u tıklayın. İşlemin tamamlanması birkaç dakika sürebilir.
Google Cloud Vision
Google Cloud Vision API, resimlerinizden analiz elde etmek için önceden eğitilmiş modelleri kullanan güçlü bir makine öğrenimi hizmetidir.
Google Cloud Vision API'yi etkinleştirme hakkında bilgi edinmek için aşağıdaki talimatları inceleyin.
Gmail API, Google Sheets API ve Google Cloud Vision API'yi etkinleştirme
Sol gezinme kenar çubuğunu tekrar açıp API'ler ve Hizmetler'i bulun. Kitaplık'ı tıklayın. API ve hizmet arayın alanına Gmail yazın. Arama sonuçlarında Gmail API'yi seçin ve Etkinleştir'i tıklayın.
API Kitaplığı sayfasına geri dönün. Google Sheets API'yi arayıp etkinleştirin.
İşlemi tekrarlayın. Cloud Vision API'yi arayıp etkinleştirin.
Google Cloud Shell'i açın
Bu laboratuvarda, çoğu işlemi gerçekleştirmek için Google Cloud Shell'i kullanacaksınız. Cloud Shell, Google Cloud Platform kaynaklarınıza doğrudan tarayıcınızdan komut satırı erişimi sağlayarak yerel makine kullanmadan yönetmenize olanak tanır.
Google Cloud Shell'i açmak için üstteki mavi yatay çubukta Cloud Shell'i Etkinleştir düğmesini tıklayın:
Ekranın alt kısmında yeni bir panel görünür:
Cloud Shell kod düzenleyiciyi başlatmak için Kod düzenleyiciyi başlat düğmesini tıklayın:
Cloud Shell kod düzenleyici yeni bir pencerede açılır.
Kodu indirme
Projeyi klonlamak için Cloud Shell'inizde aşağıdaki komutu çalıştırın:
git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git cd gcf-gmail-codelab
Cloud Shell kod düzenleyicisinde gcf-gmail-codelab adlı yeni bir klasör görünür.
3. Mimariye genel bakış
Bu laboratuvarın iş akışı aşağıda verilmiştir:
- Kullanıcı, Gmail anlık bildirimlerini ayarladığında: Gelen kutusuna yeni bir ileti her geldiğinde Gmail, Cloud Pub/Sub'a bildirim gönderir.
- Cloud Pub/Sub, yeni mesaj bildirimini Google Cloud Functions'a iletir.
- Yeni ileti bildirimi geldiğinde bir Cloud Functions örneği Gmail'e bağlanır ve yeni iletiyi alır.
- Postada ek olarak bir resim varsa Cloud Functions örneği, eki analiz etmek için Cloud Vision API'yi çağırır.
- Cloud Functions örneği, mesajı kimin gönderdiğini ve ekin nereden indirileceğini belirterek seçtiğiniz bir Google E-Tablosu'nu günceller.
4. Gmail'e erişim yetkisi verme
E-postalarınızı otomatik olarak okumak için Cloud Function'ı ayarlamadan önce Gmail'e erişimini yetkilendirmeniz gerekir. Google'a bir OAuth istemcisi kaydetmeniz ve ilişkili bir istemci kimliği oluşturmanız gerekir.
OAuth istemcisi kaydetme
Google Cloud Console'un sol gezinme menüsünde API'ler ve Hizmetler'i bulun. OAuth kullanıcı rızası ekranı'nı tıklayın.
Uygulama adı alanına GCF + Gmail Codelab gibi bir ad yazın. Diğer ayarları değiştirmeden sayfayı aşağı kaydırıp Kaydet'i tıklayın.
İlişkilendirilmiş bir istemci kimliği oluşturma
Kimlik bilgileri sekmesine geçin. Kimlik bilgisi oluştur'u tıklayın ve OAuth istemci kimliği'ni seçin. Web uygulaması türünü seçin, bir ad verin (burada tekrar GCF + Gmail Codelab'i kullanabilirsiniz) ve Oluştur'u tıklayın. Kısıtlamalar alanlarını şimdilik boş bırakın.
Pop-up pencerede döndürülen istemci kimliğini ve istemci gizli anahtarını not edin. Bu değerleri tekrar görüntülemek için sayfada müşterinizin adını tıklayabilirsiniz:
Yetkilendirme sürecini gerçekleştirme
Örnek kodda auth/index.js, yetkilendirme işlemini gerçekleştirmek için birlikte çalışan iki Cloud Functions işlevi (auth_init ve auth_callback) belirtir. Bu işlevler, az önce oluşturduğunuz istemci kimliğini ve istemci gizli anahtarını kullanır.
Kodu incelemek için Cloud Shell Kod Düzenleyici'de auth/index.js dosyasını açın.
Yetkilendirme işlemi iki tür jeton döndürür: erişim jetonları ve yenileme jetonları.
- Erişim jetonları, kimliğin kısa süreli kanıtlarıdır ve bu jetonlara sahip olan herkese verilerinize kapsamlı erişim izni verir.
auth_callback, bu jetonları Cloud Datastore'da saklar. - Yenileme jetonları, yeni erişim jetonları almak için kullanılır ve kullanım ömrü önemli ölçüde daha uzundur.
Genellikle şifrelenir ve/veya erişim jetonlarından ayrı olarak depolanır.
Cloud Shell kod düzenleyicisinde auth/env_vars.yaml dosyasını düzenleyin. YOUR-GOOGLE-CLIENT-ID ve YOUR-GOOGLE-CLIENT-SECRET değerlerini kendi değerlerinizle değiştirin. Daha fazla bilgi için önceki adıma bakın. Şimdilik YOUR-GOOGLE-CLIENT-CALLBACK-URL ve YOUR-PUBSUB-TOPIC değerlerini değiştirmeyin.
auth/env_vars.yaml dosyasını düzenledikten sonra Cloud Functions'ı dağıtmak için Cloud Shell'de aşağıdaki komutu çalıştırın:
cd ~ cd gcf-gmail-codelab/auth # Deploy Cloud Function auth_init gcloud functions deploy auth_init --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml # Deploy Cloud Function auth_callback gcloud functions deploy auth_callback --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml
Cloud Functions'ın dağıtılması birkaç dakika sürebilir. İstenirse Cloud SDK'ya beta komutlarını yükleme izni verin.
Ardından Google Cloud Console'a gidin ve sol gezinme menüsünde Cloud Functions'ı tıklayın. Cloud Functions listesinde auth_callback simgesini tıklayın ve Tetikleyici sekmesine geçin.
Sayfadaki URL'yi kopyalayın. Cloud Functions sayfasına geri dönün ve Cloud Functions listesinde auth_init simgesini tıklayın. Genel sekmesinde Düzenle'yi tıklayın. Ortam değişkenleri, ağ iletişimi, zaman aşımları ve daha fazlası'nı tıklayın ve GOOGLE_CALLBACK_URL değerini az önce kopyaladığınız URL ile değiştirin.
Değişiklikleri uygulamak için Dağıt'ı tıklayın. İşlemi tekrarlayın ve auth_callback cihazını da güncelleyin.
Son olarak, soldaki gezinme menüsünü açın ve API'ler ve Hizmetler > Alan doğrulama'yı tıklayın. Yetkilendirilmiş bir alan adı eklemek için Alan ekle'yi tıklayın. Örneğin, daha önce kopyaladığınız URL şu şekildeyse:
https://us-central1-my-project.cloudfunctions.net/auth_callback
Aşağıdakileri yetkili alan olarak eklemeniz gerekir:
us-central1-my-project.cloudfunctions.net
Onaylamak için Alan ekle'ye basın.
Kimlik bilgileri sayfasına geri dönün. OAuth istemcinizin adını tıklayın ve kopyaladığınız URL'yi Yetkili yönlendirme URI'si olarak ekleyin. Onaylamak için Enter tuşuna basın.
URL'den /auth_callback bölümünü kaldırın ve geri kalanını Yetkili JavaScript kaynağı olarak ekleyin. Örneğin, URL'niz
https://us-central1-my-project.cloudfunctions.net/auth_callback
Şunları kaynak olarak eklemeniz gerekir:
https://us-central1-my-project.cloudfunctions.net/
Onaylamak için Enter tuşuna basın ve değişiklikleri uygulamak için Kaydet'i tıklayın.
5. Gmail push bildirimlerini ayarlama
Yetkilendirme işlemi başarılı olursa auth_callback, push bildirimlerini ayarlamak için Gmail API'yi otomatik olarak çağırır.
Gmail push bildirimleri almak için bir Pub/Sub konusu oluşturmanız gerekir. Konuya abone olan herkes, Gmail'den gelen iletiler için otomatik olarak bildirim alır.
Pub/Sub konusu oluşturmak için Google Cloud Console'a gidin ve sol gezinme menüsünde Pub/Sub > Konular'ı tıklayın. Konu Oluştur'u tıklayın. Konunun adını (ör. gmail-watch) yazıp Oluştur'u tıklayın. Ayrıca, Gmail'e Pub/Sub konunuza ileti gönderme izni vermeniz gerekir: Yeni oluşturduğunuz konunun bağlam menüsünü (üç dikey nokta) tıklayın ve İzinler'i seçin; Üye ekle'yi tıklayın, gmail-api-push@system.gserviceaccount.com'ı yeni üye olarak belirtin ve Pub/Sub > Pub/Sub Yayıncısı rolünü verin; son olarak, değişiklikleri uygulamak için Kaydet'i tıklayın.
Hangi Pub/Sub konusunun kullanılacağını belirtmek için Cloud Functions işlevini auth_callback güncelleyin. Soldaki gezinme menüsünde Cloud Functions'ı tıklayın ve Cloud Functions listesinde auth_callback öğesini seçin. Genel sekmesinde Düzenle'yi tıklayın. Diğer'i tıklayın ve PUBSUB_TOPIC değerini az önce oluşturduğunuz Pub/Sub konusunun adıyla değiştirin. Değişiklikleri uygulamak için Kaydet'i tıklayın.
Artık Gmail push bildirimlerini yetkilendirmeye ve ayarlamaya hazırsınız. Yeni değişikliklerin tamamlanmasını bekleyin, ardından Cloud Functions sayfasına geri dönün, Cloud Functions listesinde auth_init simgesini seçin ve Tetikleyici sekmesine geçin. URL'yi tıkladığınızda Google ile oturum açma sayfasına yönlendirilirsiniz:
Sahibi olduğunuz bir Gmail hesabıyla oturum açın. Hesabın gelen kutusuna gelen tüm yeni iletiler push bildirimi tetikler. Oturum açtıktan sonra aşağıdaki sayfayı görürsünüz:
Erişimi yetkilendirmek için İzin ver'i tıklayın. auth_callback yetkilendirme sürecini tamamlar, erişim jetonlarını kaydeder ve sizin için Gmail anlık bildirimlerini ayarlar. Bu işlem tamamlandığında tarayıcınızda Successfully set up Gmail push notifications mesajını görürsünüz.
Bu codelab'de, yetkilendirme iş akışını sizin için otomatikleştirmek üzere @google-cloud/express-oauth2-handlers paketi kullanılır. Daha fazla bilgi için GitHub'daki deposuna bakın.
6. Gelen iletileri işleme
Daha önce de belirttiğimiz gibi, oluşturduğunuz Pub/Sub konusuna abone olan herkes gelen kutunuza yeni mesajlar geldiğinde bildirim alır. pubsub/index.js, konuya abone olarak dağıtıldıktan sonra yeni mesajları okuyacak, ekli resimleri sınıflandıracak ve bu kategorileri bir Google E-Tablosu'na aktaracak bir Cloud Function'ı (watchGmailMessages) belirtir.
Kodu incelemek için Cloud Shell Kod Düzenleyici'de pubsub/index.js dosyasını açın.
İletileri alma
Gmail anlık bildiriminde, bildirimin ilişkilendirildiği e-posta adresi ve bir geçmiş kimliği bulunur. Bu codelab'de, basitlik açısından, push bildirimi geldiğinde Gmail API'den en son iletiyi isteyeceksiniz. Daha iyi bir sonuç için ileti aramak üzere geçmiş kimliğini kullanın.
// Look up the most recent message.
const listMessagesRes = await gmail.users.messages.list({
userId: email,
maxResults: 1
});
const messageId = listMessagesRes.messages[0].id;
// Get the message using the message ID.
const message = await gmail.users.messages.get({
userId: email,
id: messageId
});
return message;
Resim eklerini analiz etme
Mesajda resim eki varsa watchGmailMessages, resmi açıklama eklemek için Cloud Vision API'yi çağırır. Bu codelab'de Cloud Vision API'den görüntüyü sınıflandırmasını ve bir dizi görüntü etiketi döndürmesini isteyeceksiniz. Örneğin, mavi gökyüzü görüntüsü sağlandığında Cloud Vision API, mavi, gökyüzü ve doğa etiketlerini döndürebilir.
watchGmailMessages, Cloud Vision API'yi çağırmak için Node.js için Cloud Vision API Kitaplığı'nı kullanır:
// Tag the attachment using Cloud Vision API
const analyzeAttachment = async (data, filename) => {
var topLabels = ['', '', ''];
if (filename.endsWith('.png') || filename.endsWith('.jpg')) {
const [analysis] = await visionClient.labelDetection({
image: {
content: Buffer.from(data, 'base64')
}
});
const labels = analysis.labelAnnotations;
topLabels = labels.map(x => x.description).slice(0, 3);
}
return topLabels;
};
Google E-Tablosu'nu güncelleme
watchGmailMessages bu analizin sonuçlarını Google E-Tablosu'na aktarır. Gönderenin adı, ekin adı ve varsa resim eklerinin etiketleri bu kapsamdadır.
Öncelikle bir Google E-Tablosu oluşturun. Google E-Tablolar'ı açın ve Yeni bir e-tablo başlatın bölümünde Boş şablonu tıklayın. Sayfanızın kimliğini kopyalayın. Örneğin, tarayıcınızdaki adres şu şekilde görünüyorsa:
https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0
E-tablonuzun kimliği abcdefghij01234567890. Cloud Shell kod düzenleyicisinde gcf-gmail-codelab/pubsub/env_vars.yaml değerini güncelleyin ve YOUR-GOOGLE-SHEET-ID değerini kendi değerinizle değiştirin.
watchGmailMessages, bilgi eklemek için Google Sheets API'ye bağlanır:
const updateReferenceSheet = async (from, filename, topLabels) => {
await googleSheets.spreadsheets.values.append({
spreadsheetId: SHEET,
range: SHEET_RANGE,
valueInputOption: 'USER_ENTERED',
requestBody: {
range: SHEET_RANGE,
majorDimension: 'ROWS',
values: [
[from, filename].concat(topLabels)
]
}
});
};
Son bir adım
Cloud Shell kod düzenleyicide gcf-gmail-codelab/pubsub/env_vars.yaml dosyasını açın ve YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET ve YOUR-GOOGLE-CALLBACK-URL değerlerini kendi değerlerinizle değiştirin. Bu değerleri Google Cloud Console'da bulabilirsiniz: Sol gezinme menüsünde Cloud Functions'ı açın, Cloud Functions listesinde auth_init öğesini seçin ve Ortam değişkenleri bölümünü bulun.
Kodu dağıtma
Cloud Function'ı dağıtmak için aşağıdaki komutu çalıştırın:
cd ~ cd gcf-gmail-codelab/pubsub gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml
Cloud Pub/Sub konunuza gmail-watch dışında bir ad verdiyseniz yukarıdaki komutta gmail-watch yerine konunuzun adını girin. Cloud Function'ın dağıtılması birkaç saniye sürebilir.
7. Deneyin
Tebrikler, tamamladınız! Kendinize resim eki içeren bir e-posta gönderin. Birkaç saniye içinde, oluşturduğunuz Google E-Tablosu'nun sağladığınız bilgilerle otomatik olarak güncellendiğini görürsünüz.