Aplikacje korzystające z przestarzałych starszych interfejsów API FCM dla protokołów HTTP i XMPP powinny jak najszybciej przeprowadzić migrację do interfejsu API HTTP v1. Oprócz ciągłego wsparcia i nowych funkcji, interfejs API HTTP v1 ma następujące zalety w porównaniu ze starszym interfejsem API:
Większe bezpieczeństwo dzięki tokenom dostępu API HTTP v1 wykorzystuje krótkotrwałe tokeny dostępu zgodnie z modelem bezpieczeństwa OAuth2. W przypadku, gdy token dostępu stanie się publiczny, można go złośliwie używać tylko przez około godzinę, zanim wygaśnie. Tokeny odświeżania nie są przesyłane tak często, jak klucze bezpieczeństwa używane w starszym interfejsie API, więc prawdopodobieństwo ich przechwycenia jest znacznie mniejsze.
Bardziej wydajne dostosowywanie wiadomości na różnych platformach W treści wiadomości interfejs API HTTP v1 ma wspólne klucze, które trafiają do wszystkich docelowych instancji, a także klucze specyficzne dla platformy, które umożliwiają dostosowywanie wiadomości na różnych platformach. Umożliwia to tworzenie „przesłonięć”, które w jednej wiadomości wysyłają nieco inne ładunki do różnych platform klienckich.
Większe możliwości rozbudowy i przyszłościowe wersje platform klienckich. Interfejs API HTTP v1 w pełni obsługuje opcje przesyłania wiadomości dostępne na platformach Apple, Android i w Internecie. Ponieważ każda platforma ma swój własny zdefiniowany blok w ładunku JSON, FCM może w razie potrzeby rozszerzyć interfejs API o nowe wersje i nowe platformy.
Zaktualizuj punkt końcowy serwera
Adres URL punktu końcowego interfejsu API HTTP v1 różni się od starszego punktu końcowego pod następującymi względami:
- Jest wersjonowany, z
/v1
w ścieżce. - Ścieżka zawiera identyfikator projektu Firebase dla Twojej aplikacji w formacie
/projects/myproject-ID/
. Ten identyfikator jest dostępny na karcie Ogólne ustawienia projektu w konsoli Firebase. - Jawnie określa metodę
send
jako:send
.
Aby zaktualizować punkt końcowy serwera dla protokołu HTTP v1, dodaj te elementy do punktu końcowego w nagłówku żądań wysłania.
Żądania HTTP wcześniej
POST https://fcm.googleapis.com/fcm/send
Żądania XMPP wcześniej
Starsze komunikaty XMPP są wysyłane przez połączenie do następującego punktu końcowego:
fcm-xmpp.googleapis.com:5235
Po
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Zaktualizuj autoryzację żądań wysyłania
Zamiast ciągu klucza serwera używanego w starszych żądaniach, żądania wysyłania HTTP v1 wymagają tokena dostępu OAuth 2.0. Jeśli do wysyłania wiadomości używasz pakietu Admin SDK, biblioteka obsługuje token za Ciebie. Jeśli używasz protokołu surowego, uzyskaj token zgodnie z opisem w tej sekcji i dodaj go do nagłówka jako Authorization: Bearer <valid Oauth 2.0 token>
.
Zanim
Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Po
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
W zależności od szczegółów środowiska serwerowego użyj kombinacji tych strategii, aby autoryzować żądania serwera kierowane do usług Firebase:
- Domyślne dane uwierzytelniające aplikacji Google (ADC)
- Plik JSON konta usługi
- Krótkoterminowy token dostępu OAuth 2.0 pochodzący z konta usługi
Jeśli Twoja aplikacja działa w Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions (w tym Cloud Functions dla Firebase), użyj domyślnych danych uwierzytelniających aplikacji (ADC). ADC używa istniejącego domyślnego konta usługi w celu uzyskania poświadczeń w celu autoryzacji żądań, a ADC umożliwia elastyczne testowanie lokalne za pośrednictwem zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS . Aby uzyskać pełną automatyzację przepływu autoryzacji, użyj ADC wraz z bibliotekami serwerowymi Admin SDK.
Jeśli Twoja aplikacja działa w środowisku serwerowym innym niż Google , musisz pobrać plik JSON konta usługi z projektu Firebase. Jeśli masz dostęp do systemu plików zawierającego plik klucza prywatnego, możesz używać zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS do autoryzacji żądań przy użyciu ręcznie uzyskanych poświadczeń. Jeśli nie masz takiego dostępu do pliku, musisz odwołać się do pliku konta usługi w swoim kodzie — co należy zrobić ze szczególną ostrożnością ze względu na ryzyko ujawnienia Twoich danych uwierzytelniających.
Podaj poświadczenia za pomocą ADC
Domyślne dane uwierzytelniające aplikacji Google (ADC) sprawdzają Twoje dane uwierzytelniające w następującej kolejności:
ADC sprawdza, czy ustawiono zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS . Jeśli zmienna jest ustawiona, ADC używa pliku konta usługi, na który wskazuje zmienna.
Jeśli zmienna środowiskowa nie jest ustawiona, ADC używa domyślnego konta usługi udostępnianego przez Compute Engine, Google Kubernetes Engine, App Engine i Cloud Functions dla aplikacji działających w tych usługach.
Jeśli ADC nie może użyć żadnego z powyższych poświadczeń, system zgłasza błąd.
Poniższy przykład kodu pakietu Admin SDK ilustruje tę strategię. Przykład nie określa jawnie poświadczeń aplikacji. Jednak funkcja ADC może niejawnie znaleźć dane uwierzytelniające, jeśli ustawiono zmienną środowiskową lub jeśli aplikacja działa w Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions.
Node.js
admin.initializeApp({
credential: admin.credential.applicationDefault(),
});
Jawa
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.getApplicationDefault())
.setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
.build();
FirebaseApp.initializeApp(options);
Pyton
default_app = firebase_admin.initialize_app()
Iść
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(),
});
Podaj poświadczenia ręcznie
Projekty Firebase obsługują konta usług Google, których możesz używać do wywoływania interfejsów API serwera Firebase z serwera aplikacji lub zaufanego środowiska. Jeśli tworzysz kod lokalnie lub wdrażasz aplikację lokalnie, możesz użyć poświadczeń uzyskanych za pośrednictwem tego konta usługi, aby autoryzować żądania serwera.
Aby uwierzytelnić konto usługi i autoryzować je do dostępu do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.
Aby wygenerować plik klucza prywatnego dla swojego konta usługi:
W konsoli Firebase otwórz Ustawienia > Konta usług .
Kliknij opcję Wygeneruj nowy klucz prywatny , a następnie potwierdź, klikając opcję Wygeneruj klucz .
Bezpiecznie przechowuj plik JSON zawierający klucz.
Podczas autoryzacji za pośrednictwem konta usługi masz dwie możliwości podania poświadczeń do aplikacji. Możesz ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS lub jawnie przekazać ścieżkę do klucza konta usługi w kodzie. Pierwsza opcja jest bezpieczniejsza i zdecydowanie zalecana.
Aby ustawić zmienną środowiskową:
Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę pliku JSON zawierającego klucz konta usługi. Ta zmienna dotyczy tylko bieżącej sesji powłoki, więc jeśli otworzysz nową sesję, ustaw zmienną ponownie.
Linux lub macOS
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
Okna
Z PowerShellem:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
Po wykonaniu powyższych kroków domyślne dane uwierzytelniające aplikacji (ADC) mogą niejawnie określić Twoje dane uwierzytelniające, umożliwiając korzystanie z danych uwierzytelniających konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.
Użyj poświadczeń, aby wybić tokeny dostępu
Użyj danych uwierzytelniających Firebase razem z biblioteką Google Auth dla preferowanego języka, aby pobrać krótkotrwały token dostępu OAuth 2.0:
węzeł.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);
});
});
}
W tym przykładzie biblioteka klienta API Google uwierzytelnia żądanie za pomocą tokena sieciowego JSON, czyli JWT. Aby uzyskać więcej informacji, zobacz tokeny internetowe JSON .
Pyton
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
Jawa
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();
}
Po wygaśnięciu tokenu dostępu metoda odświeżania tokenu jest wywoływana automatycznie w celu pobrania zaktualizowanego tokenu dostępu.
Aby autoryzować dostęp do FCM, poproś o zakres https://www.googleapis.com/auth/firebase.messaging
.
Aby dodać token dostępu do nagłówka żądania HTTP:
Dodaj token jako wartość nagłówka Authorization
w formacie Authorization: Bearer <access_token>
:
węzeł.js
headers: {
'Authorization': 'Bearer ' + accessToken
}
Pyton
headers = {
'Authorization': 'Bearer ' + _get_access_token(),
'Content-Type': 'application/json; UTF-8',
}
Jawa
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;
Zaktualizuj ładunek żądań wysłania
FCM HTTP v1 wprowadza znaczącą zmianę w strukturze ładunku komunikatu JSON. Przede wszystkim zmiany te zapewniają prawidłową obsługę wiadomości odbieranych na różnych platformach klienckich; dodatkowo zmiany zapewniają dodatkową elastyczność dostosowywania lub „zastępowania” pól wiadomości na platformę.
Oprócz sprawdzenia przykładów w tej sekcji, zobacz Dostosowywanie komunikatu na różnych platformach i przejrzyj dokumentację interfejsu API , aby zapoznać się z protokołem HTTP v1.
Przykład: proste powiadomienie
Oto porównanie bardzo prostego ładunku powiadomienia — zawierającego wyłącznie pola title
, body
i data
— pokazujące podstawowe różnice między ładunkiem starszej wersji i ładunkiem HTTP v1.
Zanim
{
"to": "/topics/news",
"notification": {
"title": "Breaking News",
"body": "New news story available."
},
"data": {
"story_id": "story_12345"
}
}
Po
{
"message": {
"topic": "news",
"notification": {
"title": "Breaking News",
"body": "New news story available."
},
"data": {
"story_id": "story_12345"
}
}
}
Przykład: kierowanie na wiele platform
Aby umożliwić kierowanie na wiele platform, starszy interfejs API wykonał zastąpienie w zapleczu. Z kolei protokół HTTP v1 zapewnia bloki kluczy specyficzne dla platformy, które sprawiają, że wszelkie różnice między platformami są wyraźne i widoczne dla programisty. Dzięki temu możesz kierować reklamy na wiele platform zawsze za pomocą jednego żądania, jak pokazano w poniższym przykładzie.
Zanim
// 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"
}
}
Po
{
"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"
}
}
}
}
}
Przykład: dostosowywanie za pomocą zastąpienia platformy
Oprócz uproszczenia wieloplatformowego kierowania wiadomości, interfejs API protokołu HTTP v1 zapewnia elastyczność dostosowywania wiadomości do każdej platformy.
Zanim
// 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"
}
}
Po
{
"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"
}
}
}
}
}
Przykład: kierowanie na określone urządzenia
Aby kierować reklamy na określone urządzenia za pomocą interfejsu API HTTP v1, podaj bieżący token rejestracji urządzenia w kluczu token
zamiast w kluczu to
.
Zanim
{ "notification": {
"body": "This is an FCM notification message!",
"time": "FCM Message"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
Po
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"body":"This is an FCM notification message!",
"title":"FCM Message"
}
}
}
Aby uzyskać więcej przykładów i informacji na temat interfejsu API FCM HTTP v1, zobacz:
Wskazówki dotyczące tworzenia żądań wysyłania serwera aplikacji za pomocą interfejsu API HTTP v1. Wszystkie fragmenty „REST” korzystają z interfejsu API wersji 1, chyba że zaznaczono inaczej.