Push bildirimleri

Genel Bakış

Reseller API, farklı Google Workspace abonelik etkinlikleri hakkında push bildirimleri göndermek için Pub/Sub API'yi kullanır. Örneğin, müşterilerinizin abonelik durumları değiştiğinde bildirim almak için push bildirimleri ayarlayabilirsiniz.

Ön koşullar

  • Google Cloud projeniz için Pub/Sub API'yi etkinleştirin.
  • Cloud projenizdeki hizmet hesabınıza Pub/Sub IAM rolleri atayın. roles/pubsub.editor rolü vermek iyi bir uzlaşmadır (kolaydır ve çok geniş değildir), ancak daha spesifik Pub/Sub izinleri kullanmak isteyebilirsiniz.

Konu oluşturma

Konu oluşturmak için resellernotify.register yöntemini kullanarak Reseller API'ye kaydolmanız gerekir. resellernotify.register yöntemi, parametre olarak bir hizmet hesabı e-posta adresi alır. Yeni oluşturduğunuz konuya yalnızca bu yöntemle yetkilendirilmiş hizmet hesapları abone olabilir.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Başarılı bir yanıt, HTTP 200 durum kodu ve Pub/Sub konu adınızı içeren bir JSON yanıtı döndürür.

Aşağıda örnek bir yanıt verilmiştir:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Konunuzu kullanması için ek hizmet hesaplarını yetkilendirmek üzere resellernotify.register numaralı telefonu tekrar arayabilirsiniz.

Hizmet hesabının erişimini iptal etme

Reseller API, resellernotify.unregister uç noktasını kullanarak hizmet hesaplarının kaydını silme olanağı da sunar:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Bir konuya abone olma

Pub/Sub konusunu oluşturduktan sonra, uygulamanızın değişiklik etkinliklerinizi nasıl kullanacağını ayarlamanız gerekir. Aşağıdaki seçeneklerden birini belirleyin:

  • Push aboneliği: HTTP POST geri çağırma işlevi sağlarsınız. Pub/Sub, uygulamanızı yeni etkinlikler hakkında bilgilendirmek için bu geri çağırma işlevini kullanır.
  • Alma aboneliği: Uygulamanız, sıraya alınan tüm değişiklikleri almak için düzenli aralıklarla bir HTTP çağrısı yapar.

Aşağıda, bir konuya abone olma isteği örneği verilmiştir:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Aşağıdakini değiştirin:

  • PROJECT: Google Cloud projeniz.
  • SUBSCRIPTION_NAME: Aboneliğinizin tanımlayıcı adı.
  • TOPIC_NAME: Daha önce oluşturduğunuz Pub/Sub konusu.
  • PUSH_NOTIFICATION_ENDPOINT: Push bildirim işleyici uç noktanız.

Başarılı bir yanıt, HTTP 200 durum kodu döndürür. Aşağıda örnek bir yanıt verilmiştir: 

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Bildirim biçimleri

Aşağıda örnek bir Pub/Sub bildirimi verilmiştir. Mesaj verileri, base64 kodlu bir JSON dizesi olarak iletilir.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Aşağıda, kod çözme işleminden sonra örnek message.data nesnesi gösterilmektedir:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Etkinlik türleri

Aşağıdaki listede tüm olası etkinlik türleri yer almaktadır:

  • NEW_SUBSCRIPTION_CREATED: Yeni bir abonelik oluşturuldu.
  • SUBSCRIPTION_TRIAL_ENDED: Aboneliğin deneme süresi sona erdi.
  • PRICE_PLAN_SWITCHED: Müşteri, esnek plandan yıllık plana geçti. Müşteri, yenileme kapsamında taahhütlü bir plandan esnek plana geçerse bu etkinlik tetiklenmez.
  • COMMITMENT_CHANGED: Yıllık taahhüt arttı veya azaldı.
  • SUBSCRIPTION_RENEWED: Yıllık abonelik yenilendi.
  • SUBSCRIPTION_SUSPENDED: Abonelik askıya alındı. subscription_suspension_reasons alanına bakın.
  • SUBSCRIPTION_SUSPENSION_REVOKED: Daha önce askıya alınmış bir abonelik için askıya alma işlemi iptal edildi.
  • SUBSCRIPTION_CANCELLED: Abonelik iptal edildi. subscription_cancellation_reason alanına bakın. Ayrıca aktarmaları tespit etmek için de kullanılabilir.

  • SUBSCRIPTION_CONVERTED: Abonelik dönüştürüldü. Bu etkinlik için bazı örnek durumlar şunlardır:

    • Doğrudan aboneliği bayi aboneliğine dönüştürme.
    • Ücretli aboneliği ek süre teklifine dönüştürme.
    • Online aboneliği çevrimdışı aboneliğe dönüştürün.

  • SUBSCRIPTION_UPGRADE: Abonelik SKU'su yükseltildi. Örneğin, abonelik Google Workspace Business Starter'dan Business Standard'a yükseltildi.

  • SUBSCRIPTION_DOWNGRADE: Abonelik SKU'su düşürüldü. Örneğin, abonelik Google Workspace Business Standard'dan Business Starter'a düşürülmüştür.

  • LICENSE_ASSIGNMENT_CHANGED: Lisans bir kullanıcıya atandı veya bir kullanıcıdan iptal edildi. Esnek aboneliklerde koltuk sayısı değişikliklerini reaktif olarak izlemek için bu etkinliği kullanabilirsiniz.

Abonelik iptali nedenleri

Abonelik iptali nedeni, event_type SUBSCRIPTION_CANCELLED olduğunda doldurulur. İptalin olası nedenleri şunlardır:

  • TRANSFERRED_OUT: Müşteri doğrudan faturalandırmaya veya başka bir bayiye geçti.
  • PURCHASE_OF_SUBSUMING_SKU: Müşteri, başka bir SKU'yu geçersiz kılan bir SKU'ya yükseltti. Örneğin, Google Workspace Business Starter ve Google Apps Kasası kullanan bir müşteri Google Workspace Business Plus'a yükseltme yaparsa Apps Kasası aboneliği, Google Workspace Business Plus'a dahil olduğu için devre dışı bırakılır.
  • RESELLER_INITIATED: Bayi aboneliği iptal etti.
  • OTHER: Abonelik, listelenen nedenlerden farklı bir nedenle iptal edilmiştir.

Aboneliğin askıya alınmasının nedenleri

Abonelik askıya alınma nedeni, event_type SUBSCRIPTION_SUSPENDED olduğunda doldurulur. Askıya alınmanın olası nedenleri şunlardır:

  • PENDING_TOS_ACCEPTANCE: Müşteri giriş yapmadı ve Google Workspace Yeniden Satılan Hizmet Şartları'nı kabul etmedi.
  • RENEWAL_WITH_TYPE_CANCEL: Müşterinin taahhüt süresi sona erdi ve hizmet, dönem sonunda iptal edildi.
  • RESELLER_INITIATED: Bayi, aboneliği manuel olarak askıya aldı.
  • TRIAL_ENDED: Müşterinin deneme süresinin dolması ve deneme dışı bir plan seçmemesi.
  • OTHER: Müşteri, Google'ın dahili bir nedeni (ör. kötüye kullanım) nedeniyle askıya alındı.

Pub/Sub sınırlamaları

Push bildirimlerinin sırası garanti edilmez. Mesajlar, aşırı durumlarda hiç teslim edilmeyebilir veya birden fazla kez teslim edilebilir. Mevcut durumu almak için değiştirilen tüm aboneliklerde reseller.subscriptions.get kullanmanızı öneririz.