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'lerle mesaj gönderme (yukarı akış mesajları dahil) özelliği 20 Haziran 2023'te kullanımdan kaldırılmıştır ve 21 Haziran 2024'te kaldırılacaktır.

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

HTTP v1 API, sürekli destek ve yeni özelliklere ek olarak eski API'lere göre şu avantajlara sahiptir:

  • Erişim jetonları aracılığıyla 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, süresi dolmadan önce kötü niyetli bir şekilde yaklaşık bir saat boyunca kullanılabilir. Yenileme jetonları, eski API'de kullanılan güvenlik anahtarları kadar sık iletilmediğinden bunların yakalanma olasılığı çok daha düşüktür.

  • Platformlar genelinde mesajların daha etkili şekilde özelleştirilmesi Mesaj gövdesi için HTTP v1 API'de, hedeflenen tüm örneklere giden ortak anahtarlar ve mesajı platformlar genelinde özelleştirmenizi sağlayan platforma özel anahtarlar bulunur. Böylece tek bir mesajda, farklı istemci 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'si Apple platformlarında, Android'de ve web'de kullanılabilen mesajlaşma seçeneklerini tam olarak destekler. Her platformun JSON yükünde kendi tanımlı bir bloğu olduğundan, FCM gerektiğinde API'yi yeni sürümlere ve yeni platformlara genişletebilir.

Sunucu uç noktasını güncelleyin

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

  • Yolu /v1 olacak şekilde sürümü oluşturulmuştur.
  • Yol, uygulamanız için Firebase projesinin /projects/myproject-ID/ biçimindeki proje kimliğini içerir. Bu kimlik Firebase konsolunun Genel proje ayarları sekmesinde bulunur.
  • send yöntemini :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.

Önceki HTTP istekleri

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

Şu tarihten önceki XMPP istekleri:

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

fcm-xmpp.googleapis.com:5235

Sonra

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

Gönderme isteklerinin yetkilendirmesini güncelleyin

Eski isteklerde kullanılan sunucu anahtarı dizesi yerine, HTTP v1 gönderme istekleri için OAuth 2.0 erişim jetonu gerekir. Mesaj göndermek için Yönetici SDK'sını kullanıyorsanız kitaplık, jetonu sizin için yönetir. Ham protokol kullanıyorsanız jetonu bu bölümde açıklandığı şekilde alın ve Authorization: Bearer <valid Oauth 2.0 token> olarak başlığa 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, sunucu isteklerini Firebase hizmetlerine yetkilendirmek için şu stratejilerin bir kombinasyonunu kullanın:

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

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

Uygulamanız Google dışı 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 istekleri manuel olarak alınan bu kimlik bilgileriyle yetkilendirmek için GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini kullanabilirsiniz. Bu tür bir dosya erişiminiz yoksa kodunuzda hizmet hesabı dosyasına referans vermeniz gerekir. Kimlik bilgilerinizin açığa çıkma riskinden dolayı bu işlemi son derece dikkatli bir şekilde yapmanız gerekir.

ADC kullanarak kimlik bilgisi sağlayın

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 ayarlanmışsa ADC, değişkenin işaret ettiği hizmet hesabı dosyasını kullanır.

  2. Ortam değişkeni ayarlanmamışsa 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 bilgilerinin hiçbirini kullanamazsa sistem bir hata verir.

Aşağıdaki Yönetici SDK'si kod örneğinde bu strateji gösterilmektedir. Örnek, uygulama kimlik bilgilerini açıkça belirtmemektedir. Ancak ADC, ortam değişkeni ayarlandığı veya uygulama Compute Engine, Google Kubernetes Engine, App Engine ya da Cloud Functions'ta çalıştığı sürece kimlik bilgilerini dolaylı yoldan 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, uygulama sunucunuzdan veya güvenilir ortamınızdan Firebase sunucu API'lerini çağırmak için kullanabileceğiniz Google hizmet hesaplarını destekler. Yerel olarak kod geliştiriyorsanız veya uygulamanızı şirket içinde dağıtıyorsanız sunucu isteklerini yetkilendirmek için bu hizmet hesabından alınan kimlik bilgilerini kullanabilirsiniz.

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

Hizmet hesabınıza ait özel anahtar dosyası oluşturmak için:

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

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

  3. Anahtarı içeren JSON dosyasını güvenli bir şekilde saklayı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 yolu, kodda hizmet hesabı anahtarına açık bir şekilde aktarabilirsiniz. İ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

PowerShell 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 ederken veya çalıştırırken hizmet hesabı kimlik bilgilerini kullanabilirsiniz.

Erişim jetonlarını bastırmak için kimlik bilgilerini kullanma

Kısa ömürlü bir OAuth 2.0 erişim jetonu almak için Firebase kimlik bilgilerinizi Google Kimlik Doğrulama Kitaplığı ile birlikte tercih ettiğiniz dilde 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ı konusuna 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, güncellenmiş bir erişim jetonunu almak için jeton yenileme yöntemi 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 bir HTTP istek başlığına eklemek için:

Jetonu Authorization başlığının değeri olarak Authorization: Bearer <access_token> biçiminde 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şiklik içeriyor. Öncelikle bu değişiklikler, mesajların farklı istemci platformlarında alındıklarında doğru şekilde işlenmesini sağlar. Ayrıca değişiklikler, her platform için mesaj alanlarını özelleştirme veya "geçersiz kılma" konusunda size daha fazla esneklik sunar.

Bu bölümdeki örnekleri incelemeye ek olarak Bir mesajı platformlar arasında özelleştirme bölümüne bakın ve HTTP v1 hakkında bilgi edinmek için API referansını inceleyin.

Örnek: basit bildirim mesajı

Eski ve HTTP v1 yükleri arasındaki temel farkları gösteren, yalnızca title, body ve data alanlarını içeren çok basit bir bildirim yükünün karşılaştırmasını burada bulabilirsiniz.

Ö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: birden fazla platformu hedefleme

Çoklu platform hedeflemeyi etkinleştirmek için eski API arka uçta geçersiz kılma işlemleri gerçekleştirdi. Buna karşılık HTTP v1, platformlar arasındaki farkları açık ve geliştiriciye görünür hale getiren platforma özel anahtar blokları sağlar. Bu, aşağıdaki örnekte gösterildiği gibi, tek bir istekle her zaman birden çok platformu hedeflemenize olanak tanır.

Ö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ı platform başına ö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

Belirli cihazları HTTP v1 API ile 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: