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

HTTP ve XMPP için desteği sonlandırılan FCM eski API'lerini kullanan uygulamalar, en kısa sürede HTTP v1 API'ye geçmelidir. Bu API'lerle ileti gönderme (yukarı akış iletileri dahil) 20 Haziran 2023'te kullanımdan kaldırıldı ve kapatma süreci 22 Temmuz 2024'te başlayacak.

Etkilenen özellikler hakkında daha fazla bilgi edinin.

HTTP v1 API, devam eden destek ve yeni özelliklere ek olarak eski API'lere kıyasla şu avantajları sunar:

  • 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 hâle gelmesi durumunda, jetonun süresi dolmadan önce yalnızca yaklaşık bir saat boyunca kötü amaçlı olarak kullanılabilir. Yenileme jetonları, eski API'de kullanılan güvenlik anahtarları kadar sık iletilmediğinden yakalanma olasılıkları çok daha düşüktür.

  • Platformlar arası mesajların daha verimli şekilde özelleştirilmesi HTTP v1 API'sinde, mesaj gövdesi için tüm hedeflenen örneklere giden ortak anahtarların yanı sıra platformlar arası mesajı özelleştirmenize olanak tanıyan platforma özel anahtarlar bulunur. Bu sayede, tek bir mesajda farklı istemci platformlarına biraz farklı yükler 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 tanımlanmış kendi 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'sinin uç nokta URL'si, eski uç noktadan şu açılardan farklıdır:

  • Yolda /v1 ile sürüm oluşturulur.
  • Yol, uygulamanızın 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, gönderme isteklerinizin başlığındaki uç noktaya şu öğeleri ekleyin.

HTTP istekleri önce

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

XMPP istekleri önce

Eski XMPP mesajları, aşağıdaki uç noktaya 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 istekleri, eski isteklerde kullanılan sunucu anahtarı dizesi yerine OAuth 2.0 erişim jetonu gerektirir. İleti göndermek için Admin SDK'sını kullanıyorsanız kitaplık, jetonu sizin için işler. Ham protokol kullanıyorsanız bu bölümde açıklandığı şekilde jetonu alın ve Authorization: Bearer <valid Oauth 2.0 token> olarak üstbilgiye 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 yönelik sunucu isteklerini yetkilendirmek için bu 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 (Cloud Functions for Firebase dahil) çalışıyorsa varsayılan uygulama kimlik bilgilerini (ADC) kullanın. ADC, istekleri yetkilendirmek için kimlik bilgilerini almak üzere mevcut varsayılan hizmet hesabınızı kullanır ve GOOGLE_APPLICATION_CREDENTIALS ortam değişkeni aracılığıyla esnek yerel testlere olanak tanır. Yetkilendirme akışının en kapsamlı şekilde otomatikleştirilmesi için ADC'yi Yönetici SDK'sı 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şebildiğiniz sürece, ortam değişkeni GOOGLE_APPLICATION_CREDENTIALS'yı kullanarak bu manuel olarak edinilmiş kimlik bilgileriyle istekleri yetkilendirebilirsiniz. Bu tür dosya erişiminiz yoksa kodunuzda hizmet hesabı dosyasına referans vermeniz gerekir. Bu işlem, kimlik bilgilerinizin açığa çıkma riski nedeniyle son derece dikkatli bir şekilde yapılmalıdır.

ADC kullanarak kimlik bilgileri sağlama

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

  1. ADC, ortam değişkeni GOOGLE_APPLICATION_CREDENTIALS'nin 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 bilgilerinden hiçbirini kullanamazsa sistem hata verir.

Aşağıdaki Admin SDK kod örneğinde bu strateji gösterilmektedir. Örnekte uygulama kimlik bilgileri açıkça belirtilmiyor. Ancak, ortam değişkeni ayarlandığı veya uygulama Compute Engine, Google Kubernetes Engine, App Engine ya da Cloud Functions üzerinde çalıştığı sürece ADC, kimlik bilgilerini örtülü 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)
}
init.go

C#

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

Kimlik bilgilerini manuel olarak sağlama

Firebase projeleri, uygulamanızın sunucusundan veya güvenilir ortamdan Firebase sunucu API'lerini çağırmak için kullanabileceğiniz Google hizmet hesaplarını destekler. Kodu yerel olarak geliştiriyorsanız veya uygulamanızı şirket içinde dağıtıyorsanız sunucu isteklerini yetkilendirmek için bu hizmet hesabı üzerinden 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ı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, ardından Anahtar Oluştur'u tıklayarak onaylayın.

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

Bir hizmet hesabı üzerinden yetkilendirirken uygulamanıza kimlik bilgilerini sağlamak için iki seçeneğiniz vardır. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlayabilir veya hizmet hesabı anahtarının yolunu kodda açıkça iletebilirsiniz. İ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ı tamamladıktan sonra, Uygulama Varsayılan Kimlik Bilgileri (ADC) kimlik bilgilerinizi örtülü olarak belirleyebilir. Bu sayede, Google dışı ortamlarda test yaparken veya çalıştırırken hizmet hesabı kimlik bilgilerini kullanabilirsiniz.

Erişim jetonları oluşturmak için kimlik bilgilerini kullanma

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

node.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);
    });
  });
}
index.js

Bu örnekte, Google API istemci kitaplığı isteği bir JSON web jetonu (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
messaging.py

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();
}
Messaging.java

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

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

Erişim jetonunu bir HTTP istek üstbilgisine eklemek için:

Jetonu, Authorization üstbilgisinin değeri olarak Authorization: Bearer <access_token> biçiminde ekleyin:

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

Python

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

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;
FirebaseMessagingSnippets.java

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

FCM HTTP v1, JSON mesajı yükünün yapılandırılmasında önemli bir değişiklik sunar. Bu değişiklikler öncelikle iletilerin farklı istemci platformlarında alındığında doğru şekilde işlenmesini sağlar. Ayrıca, değişiklikler sayesinde ileti alanlarını platforma göre özelleştirme veya "geçersiz kılma" konusunda daha fazla esneklik elde edersiniz.

Bu bölümdeki örnekleri incelemenin yanı sıra Platformlar arası mesajları özelleştirme başlıklı makaleyi inceleyin ve HTTP v1 hakkında bilgi edinmek için API referansını gözden geçirin.

Örnek: basit bildirim mesajı

Yalnızca title, body ve data alanlarını içeren çok basit bir bildirim yükünün karşılaştırması aşağıda verilmiştir. Bu karşılaştırma, eski ve HTTP v1 yüklerindeki temel farkları gösterir.

Ö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 Messaging API'nin aksine, HTTP v1 API'si data alanında iç içe yerleştirilmiş JSON değerlerini desteklemez. JSON'dan dizeye dönüştürme gereklidir.

Önce

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

Sonra

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

Örnek: Birden fazla platformu hedefleme

Eski API, çoklu platform hedeflemeyi etkinleştirmek için arka uçta geçersiz kılmalar gerçekleştiriyordu. Buna karşılık HTTP v1, platformlar arasındaki farkları geliştiriciye açık ve görünür kılan platforma özgü anahtar blokları sağlar. Bu sayede, aşağıdaki örnekte gösterildiği gibi her zaman tek bir istekle birden fazla 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ı hedeflenmesini basitleştirmenin yanı sıra 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 to anahtarı yerine token anahtarında cihazın mevcut kayıt jetonunu sağlayın.

Önce

  { "notification": {
      "body": "This is an FCM notification message!",
      "title": "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: