Eski FCM API'lerinden HTTP v1'e geçiş

HTTP ve XMPP için desteği sonlandırılmış FCM eski API'lerini kullanan uygulamalar en kısa sürede HTTP v1 API'ye geçmelidir. Bu API'leri kullanarak mesaj gönderme (yukarı akış mesajları dahil) 20 Haziran 2023'te kullanımdan kaldırıldı ve 22 Temmuz 2024'ten itibaren kapatma işlemi başlayacak.

Etkilenen belirli özellikler hakkında daha fazla bilgi edinin.

HTTP v1 API, sürekli destek ve yeni özelliklerin yanı sıra eski API'lere göre şu avantajlara sahiptir:

  • Erişim jetonları ile daha iyi güvenlik HTTP v1 API, OAuth2 güvenlik modeline göre kısa ömürlü erişim jetonları kullanır. Bir erişim jetonunun herkese açık hale gelmesi durumunda, jetonun süresi dolmadan önce yalnızca bir saat kadar kötü amaçlı olarak kullanılabilir. Yenileme jetonları eski API'de kullanılan güvenlik anahtarları kadar sık iletilmez. Bu nedenle, bunların yakalanma olasılığı çok daha düşüktür.

  • Farklı platformlarda mesajların daha verimli bir şekilde özelleştirilmesi Mesaj gövdesi için HTTP v1 API, hedeflenen tüm örneklere giden ortak anahtarlara ve mesajı platformlar arasında özelleştirmenize olanak tanıyan platforma özel anahtarlara sahiptir. Böylece tek bir mesajla farklı müşteri platformlarına biraz farklı yük gönderen "geçersiz kılmalar" oluşturabilirsiniz.

  • Yeni istemci platformu sürümleri için daha genişletilebilir ve geleceğe hazır HTTP v1 API, Apple platformları, Android ve web'de bulunan mesajlaşma seçeneklerini tam olarak destekler. Her platformun JSON yükünde kendine ait bir bloğu olduğundan FCM, gerektiğinde API'yi yeni sürümlere ve yeni platformlara genişletebilir.

Sunucu uç noktasını güncelleme

HTTP v1 API'nin uç nokta URL'si, eski uç noktadan şu yönleriyle farklıdır:

  • Bu URL'nin sürümü oluşturulmuş ve yolda /v1 bulunuyor.
  • Yol, uygulamanıza ait Firebase projesinin proje kimliğini /projects/myproject-ID/ biçiminde içerir. Bu kimlik, Firebase konsolunun Genel proje ayarları sekmesinde bulunur.
  • send yöntemini açıkça :send olarak belirtir.

HTTP v1 için sunucu uç noktasını güncellemek üzere bu öğeleri gönderme isteklerinizin başlığındaki uç noktaya ekleyin.

Şu tarihten önceki HTTP istekleri:

POST https://fcm.googleapis.com/fcm/send

Şu tarihten önceki XMPP istekleri:

Eski XMPP mesajları, aşağıdaki uç noktaya bir bağlantı üzerinden gönderilir:

fcm-xmpp.googleapis.com:5235

Sonra

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Gönderme isteklerinin yetkilendirmesini güncelleme

HTTP v1 gönderme isteklerinde, eski isteklerde kullanılan sunucu anahtarı dizesi yerine OAuth 2.0 erişim jetonu gerekir. Mesaj göndermek için Admin SDK'yı kullanıyorsanız kitaplık, jetonu sizin için işler. Ham protokolü kullanıyorsanız jetonu bu bölümde açıklandığı şekilde alın ve başlığa Authorization: Bearer <valid Oauth 2.0 token> olarak ekleyin.

Önce

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Sonra

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

Sunucu ortamınızın ayrıntılarına bağlı olarak, Firebase hizmetlerine sunucu isteklerini yetkilendirmek için şu stratejileri bir arada kullanın:

  • Google Uygulaması Varsayılan Kimlik Bilgileri (ADC)
  • Hizmet hesabı JSON dosyası
  • Bir hizmet hesabından türetilen kısa ömürlü bir OAuth 2.0 erişim jetonu

Uygulamanız Compute Engine, Google Kubernetes Engine, App Engine veya Cloud Functions'da çalışıyorsa (Firebase için Cloud Functions dahil) Uygulama Varsayılan Kimlik Bilgilerini (ADC) kullanın. ADC, istekleri yetkilendirmek üzere kimlik bilgilerini almak için mevcut varsayılan hizmet hesabınızı kullanır. ADC ise GOOGLE_APPLICATION_CREDENTIALS ortam değişkeni üzerinden esnek yerel test yapılmasını sağlar. Yetkilendirme akışının tam otomasyonu için ADC'yi Yönetici SDK'sı sunucu kitaplıklarıyla birlikte kullanın.

Uygulamanız Google harici bir sunucu ortamında çalışıyorsa Firebase projenizden bir hizmet hesabı JSON dosyası indirmeniz gerekir. Özel anahtar dosyasını içeren bir dosya sistemine erişiminiz olduğu sürece, manuel olarak alınan bu kimlik bilgileriyle istekleri yetkilendirmek için GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini kullanabilirsiniz. Böyle bir dosyaya erişiminiz yoksa kodunuzda hizmet hesabı dosyasına referans vermeniz gerekir. Bu işlem, kimlik bilgilerinizin açığa çıkma riskinden dolayı son derece dikkatli bir şekilde yapılmalıdır.

ADC kullanarak kimlik bilgisi sağlama

Google Uygulaması Varsayılan Kimlik Bilgileri (ADC), kimlik bilgilerinizi aşağıdaki sırayla kontrol eder:

  1. ADC, GOOGLE_APPLICATION_CREDENTIALS ortam değişkeninin ayarlanıp ayarlanmadığını kontrol eder. Değişken ayarlanırsa ADC, değişkenin işaret ettiği hizmet hesabı dosyasını kullanır.

  2. Ortam değişkeni ayarlanmadıysa ADC, Compute Engine, Google Kubernetes Engine, App Engine ve Cloud Functions'ın bu hizmetlerde çalışan uygulamalar için sağladığı varsayılan hizmet hesabını kullanır.

  3. ADC yukarıdaki kimlik bilgilerinden herhangi birini kullanamazsa sistem bir hata verir.

Aşağıdaki Yönetici SDK'sı kod örneğinde bu strateji gösterilmektedir. Örnekte, uygulama kimlik bilgileri açık bir şekilde belirtilmemektedir. Ancak ADC, ortam değişkeni ayarlandığı veya uygulama Compute Engine, Google Kubernetes Engine, App Engine ya da Cloud Functions'da çalıştığı sürece kimlik bilgilerini dolaylı olarak bulabilir.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

Kimlik bilgilerini manuel olarak sağlayın

Firebase projeleri, Google hizmet hesaplarını destekler. Bu hesapları, uygulama sunucunuzdan veya güvenilir ortamınızdan Firebase sunucusu API'lerini çağırmak için kullanabilirsiniz. Kodları yerel olarak geliştiriyor veya uygulamanızı şirket içinde dağıtıyorsanız sunucu isteklerini yetkilendirmek için bu hizmet hesabı aracılığıyla edinilen kimlik bilgilerini kullanabilirsiniz.

Bir hizmet hesabının kimliğini doğrulamak ve bu hesabı Firebase hizmetlerine erişmesi için yetkilendirmek üzere JSON biçiminde bir özel anahtar dosyası oluşturmanız gerekir.

Hizmet hesabınız için özel anahtar dosyası oluşturmak üzere:

  1. Firebase konsolunda Ayarlar > Hizmet Hesapları'nı açın.

  2. Yeni Özel Anahtar Oluştur'u tıklayın ve ardından Anahtar Oluştur'u tıklayarak onaylayın.

  3. Anahtarı içeren JSON dosyasını güvenli bir şekilde depolayın.

Bir hizmet hesabı aracılığıyla yetkilendirme yaparken kimlik bilgilerini uygulamanıza sağlamak için iki seçeneğiniz vardır. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlayabilir veya kodda hizmet hesabı anahtarına giden yolu açıkça geçirebilirsiniz. İlk seçenek daha güvenlidir ve kesinlikle önerilir.

Ortam değişkenini ayarlamak için:

GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini, hizmet hesabı anahtarınızı içeren JSON dosyasının dosya yoluna ayarlayın. Bu değişken yalnızca mevcut kabuk oturumunuz için geçerlidir. Bu nedenle, yeni bir oturum açarsanız değişkeni tekrar ayarlayın.

Linux veya macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

Powerpoint ile:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Yukarıdaki adımları tamamlamanızın ardından Uygulama Varsayılan Kimlik Bilgileri (ADC), kimlik bilgilerinizi dolaylı olarak belirleyebilir. Bu sayede, Google dışı ortamlarda test yaparken veya çalıştırırken hizmet hesabı kimlik bilgilerini kullanabilirsiniz.

Erişim jetonlarını basmak için kimlik bilgilerini kullanın

Kısa ömürlü bir OAuth 2.0 erişim jetonu almak için Firebase kimlik bilgilerinizi, tercih ettiğiniz dilde Google Auth Kitaplığı ile birlikte kullanın:

düğüm.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

Bu örnekte, Google API istemci kitaplığı, isteğin kimliğini bir JSON web jetonu veya JWT ile doğrular. Daha fazla bilgi için JSON web jetonları bölümüne bakın.

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}

Erişim jetonunuzun süresi dolduktan sonra jeton yenileme yöntemi, güncellenmiş bir erişim jetonunu almak için otomatik olarak çağrılır.

FCM'ye erişimi yetkilendirmek için https://www.googleapis.com/auth/firebase.messaging kapsamını isteyin.

Erişim jetonunu HTTP istek başlığına eklemek için:

Jetonu Authorization: Bearer <access_token> biçiminde Authorization başlığının değeri olarak ekleyin:

düğüm.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

Java

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;

Gönderme isteklerinin yükünü güncelleme

FCM HTTP v1, JSON mesaj yükünün yapısında önemli bir değişikliğe yol açmıştır. Öncelikle, bu değişiklikler farklı istemci platformlarında alınan mesajların doğru şekilde işlenmesini sağlar. Ayrıca değişiklikler, mesaj alanlarını platforma göre özelleştirme veya "geçersiz kılma" konusunda ek esneklik sağlar.

Bu bölümdeki örnekleri incelemenin yanı sıra mesajları platformlar arasında özelleştirme bölümüne göz atın ve HTTP v1 hakkında bilgi edinmek için API referansını inceleyin.

Örnek: basit bildirim mesajı

Aşağıda, yalnızca title, body ve data alanlarını içeren çok basit bir bildirim yükünün, eski ve HTTP v1 yükleri arasındaki temel farkları gösteren bir karşılaştırması verilmiştir.

Önce

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

Sonra

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

Örnek: iç içe yerleştirilmiş JSON verileri

Eski mesajlaşma API'sinin aksine HTTP v1 API, data alanında iç içe yerleştirilmiş JSON değerlerini desteklemez. JSON'den dizeye dönüşüm gereklidir.

Önce

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

Sonra

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

Örnek: birden fazla platformu hedefleme

Çoklu platform hedeflemeyi etkinleştirmek için eski API, arka uçta geçersiz kılma işlemleri gerçekleştirilir. Buna karşılık HTTP v1, platformlar arasında açık ve geliştiriciye açık şekilde fark yaratan, platforma özgü anahtar blokları sağlar. Böylece, aşağıdaki örnekte gösterildiği gibi her zaman tek bir istekle birden çok platformu hedefleyebilirsiniz.

Önce

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

Sonra

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Örnek: platform geçersiz kılmalarıyla özelleştirme

HTTP v1 API, mesajların platformlar arası hedeflemesini basitleştirmenin yanı sıra mesajları platforma göre özelleştirme esnekliği de sunar.

Önce

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

Sonra

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Örnek: belirli cihazları hedefleme

HTTP v1 API ile belirli cihazları hedeflemek için cihazın geçerli kayıt jetonunu to anahtarı yerine token anahtarında sağlayın.

Önce

  { "notification": {
      "body": "This is an FCM notification message!",
      "time": "FCM Message"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }

Sonra

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

FCM HTTP v1 API hakkında daha fazla örnek ve bilgi için aşağıdakilere bakın: