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

HTTP ve XMPP için desteği sonlandırılan eski FCM 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ıldı ve kapatma işlemi 22 Temmuz 2024'te başlayacak.

Etkilenen özellikler hakkında daha fazla bilgi edinin.

HTTP v1 API, sürekli destek ve yeni özelliklerin yanı sıra eski API'lere kıyasla aşağıdaki avantajlara sahiptir:

  • Erişim jetonları ile daha iyi güvenlik HTTP v1 API, OAuth2 güvenlik modeline uygun olarak 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 iletilmediğinden yakalanma olasılıkları ç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 fazla genişletilebilir ve geleceğe hazır HTTP v1 API, Apple platformları, Android ve Web'de kullanılabilen mesajlaşma seçeneklerini tam olarak destekler. Her platformun JSON yükünde kendine ait bir bloğu olduğundan FCM, API'yi gerektiğinde yeni sürümlere ve yeni platformlara genişletebilir.

Sunucu uç noktasını güncelleme

HTTP v1 API'sinin uç noktası URL'si, eski uç noktadan şu açılardan farklıdır:

  • Yolda /v1 ile sürümlendirilir.
  • Yol, uygulamanız için Firebase projesinin proje kimliğini /projects/myproject-ID/ biçiminde içerir. Bu kimliği Firebase konsolunun Genel proje ayarları sekmesinde bulabilirsiniz.
  • send yöntemini :send olarak açıkça 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

Önceki XMPP istekleri

Eski XMPP mesajları, aşağıdaki uç noktaya bağlanan 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

Eski isteklerde kullanılan sunucu anahtarı dizesi yerine HTTP v1 gönderme isteklerinde 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ığı gibi edinin 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 isteklerine yetki vermek için aşağıdaki stratejilerin bir kombinasyonunu kullanın:

  • Google Uygulaması Varsayılan Kimlik Bilgileri (ADC)
  • Hizmet hesabı JSON dosyası
  • 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 (Cloud Functions for Firebase dahil) üzerinde çalışıyorsa Uygulama Varsayılan Kimlik Bilgileri'ni (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 test yapmanızı 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 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, manuel olarak alınan bu kimlik bilgileriyle istekleri yetkilendirmek için GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini kullanabilirsiniz. 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'yi kullanarak kimlik bilgileri sağlama

Google Uygulama 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 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 bir hata verir.

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

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 sunucu API'lerini çağırmak için kullanabilirsiniz. Yerel olarak kod geliştiriyorsanız veya uygulamanızı şirket içinde dağıtıyorsanız sunucu isteklerine yetki vermek için bu hizmet hesabı aracılığıyla edinilen 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 ve 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 yetki verirken uygulamanıza kimlik bilgilerini sağlama konusunda 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 dolaylı olarak belirleyebilir. Böylece, Google dışı ortamlarda test ederken veya çalıştırırken hizmet hesabı kimlik bilgilerini kullanabilirsiniz.

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

Kısa süreli bir OAuth 2.0 erişim jetonu almak için Firebase kimlik bilgilerinizi tercih ettiğiniz dildeki Google Auth Library 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);
    });
  });
}
index.js

Bu örnekte Google API istemci kitaplığı, isteğin kimliğini JSON web jetonu veya JWT ile doğrular. Daha fazla bilgi için JSON web jetonları başlıklı makaleyi inceleyin.

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 jeton yenileme yöntemi, güncellenmiş bir erişim jetonunu almak için otomatik olarak çağrılır.

FCM'e erişim yetkisi vermek 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
}
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ısında önemli bir değişikliğe yol açmıştır. Bu değişiklikler öncelikle, iletilerin farklı istemci platformlarında alındığında doğru şekilde işlenmesini sağlar. Ayrıca, platform başına ileti alanlarını özelleştirmek veya "üst yazmak" için size ek esneklik sunar.

Bu bölümdeki örnekleri incelemenin yanı sıra HTTP v1 ile ilgili bilgi edinmek için Bir mesajı platformlar arasında özelleştirme başlıklı makaleyi inceleyin ve API referansını inceleyin.

Örnek: basit bildirim mesajı

Eski ve HTTP v1 yüklerinde temel farklılıkları gösteren, 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.

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

Önce

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

Sonra

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

Örnek: birden fazla platformu hedefleme

Eski API, çok platformlu hedeflemeyi etkinleştirmek için arka uçta geçersiz kılma işlemleri gerçekleştiriyordu. 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. 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ı 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 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: