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 anlık bildirimler ayarlayabilirsiniz.

Ön koşullar

  • Google Cloud projeniz için Pub/Sub API'yi etkinleştirin.
  • Cloud projenizde hizmet hesabınıza Pub/Sub IAM rolleri atayın. roles/pubsub.editor rolünü vermek iyi bir uzlaşma çözümüdür (kolay ve çok geniş kapsamlı 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. Yalnızca bu yöntemle yetkilendirilmiş hizmet hesapları yeni oluşturduğunuz konuya 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 kullanmak üzere ek hizmet hesaplarını yetkilendirmek için resellernotify.register işlevini tekrar çağırabilirsiniz.

Bir 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 tüketeceğini 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ğırmayı kullanır.
  • Çekme aboneliği: Uygulamanız, sıraya alınmış tüm değişiklikleri almak için düzenli olarak 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ğiniz için tanımlayıcı bir ad.
  • TOPIC_NAME: Daha önce oluşturduğunuz Pub/Sub konusu.
  • PUSH_NOTIFICATION_ENDPOINT: Push bildirimi 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. İleti 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 sonraki message.data nesnesi örneği verilmiştir:

{
  "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 olası tüm etkinlik türleri yer almaktadır:

  • NEW_SUBSCRIPTION_CREATED: Yeni bir abonelik oluşturuldu.
  • SUBSCRIPTION_TRIAL_ENDED: Bir 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 artırıldı veya azaltıldı.
  • 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 aboneliğin askıya alınma durumu iptal edildi.
  • SUBSCRIPTION_CANCELLED: Abonelik iptal edildi. subscription_cancellation_reason alanına bakın. Ayrıca transferleri tespit etmek için de kullanılabilir.

  • SUBSCRIPTION_CONVERTED: Abonelik dönüştürüldü. Bu etkinliğe ilişkin bazı örnekler aşağıda verilmiştir:

    • 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ürme

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

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

  • LICENSE_ASSIGNMENT_CHANGED: Lisans bir kullanıcıya atanmış veya kullanıcıdan iptal edilmiş. Bu etkinliği, esnek aboneliklerdeki koltuk sayısı değişikliklerini reaktif olarak izlemek için kullanabilirsiniz.

Abonelik iptali nedenleri

Abonelik iptali nedeni, event_type olduğunda SUBSCRIPTION_CANCELLED. Olası iptal nedenleri şunlardır:

  • TRANSFERRED_OUT: Müşteri, doğrudan faturalandırmaya veya başka bir bayiye aktarılmıştır.
  • PURCHASE_OF_SUBSUMING_SKU: Müşteri, başka bir SKU'yu geçersiz kılan bir SKU'ya yükseltme yaptı. Ö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 kapsanır.
  • RESELLER_INITIATED: Bayi, aboneliği iptal etti.
  • OTHER: Abonelik, listelenenler dışında bir nedenle iptal edildi.

Aboneliğin askıya alınma nedenleri

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

  • PENDING_TOS_ACCEPTANCE: Müşteri, Google Workspace Resold Hizmet Şartları'nı kabul etmedi ve oturum açmadı.
  • RENEWAL_WITH_TYPE_CANCEL: Müşterinin taahhüdü sona erdi ve hizmeti dönem sonunda iptal edildi.
  • RESELLER_INITIATED: Bayi, aboneliği manuel olarak askıya aldı.
  • TRIAL_ENDED: Müşterinin deneme süresi sona erdi ve müşteri deneme sürümü olmayan bir plan seçmedi.
  • OTHER: Müşteri, Google'ın dahili bir nedeni (ör. kötüye kullanım) nedeniyle askıya alınmıştır.

Pub/Sub sınırlamaları

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