Przejście ze starszych interfejsów API FCM na HTTP v1

Aplikacje korzystające z wycofanych starszych interfejsów API FCM dla HTTP i XMPP należy przenieść na interfejsu API HTTP w wersji 1. Wysyłanie wiadomości (w tym wiadomości nadrzędne) z tymi interfejsami API zostały wycofane 20 czerwca 2023 r. Wyłączenie nastąpi 22 lipca 2024 r.

Dowiedz się więcej o konkretnych funkcjach, których dotyczy problem.

Oprócz ciągłego wsparcia i nowych funkcji interfejs HTTP v1 API ma także następujące zalety w porównaniu ze starszymi interfejsami API:

  • Większe bezpieczeństwo dzięki tokenom dostępu Interfejs HTTP v1 API korzysta z dostępu krótkotrwałego tokeny zgodnie z modelem zabezpieczeń OAuth2. W przypadku, gdy token dostępu staje się publiczny i można go użyć tylko złośliwie na około godzinę wcześniej wygasa. Tokeny odświeżania nie są przesyłane tak często, jak używane klucze bezpieczeństwa w starszym interfejsie API, więc prawdopodobieństwo ich przechwycenia jest znacznie mniejsze.

  • Bardziej efektywne dostosowanie komunikatów na różnych platformach W przypadku przekazu treść, interfejs API HTTP w wersji 1 ma wspólne klucze, które trafiają do wszystkich docelowych instancji, oraz klucze właściwe dla platformy które pozwalają dostosować przekaz do różnych platform. Dzięki temu możesz: utwórz „zastąpienia” które wysyłają nieco inne ładunki platformy klientów w pojedynczej wiadomości.

  • Większa elastyczność i przyszłość dla nowych wersji platform klienckich Interfejs HTTP v1 API w pełni obsługuje opcje wiadomości dostępne na platformach Apple, Androidzie Sieć. Ponieważ każda platforma ma własny zdefiniowany blok w ładunku JSON, FCM może rozszerzać interfejs API na nowe wersje i platformy w razie potrzeby.

Zaktualizuj punkt końcowy serwera

Adres URL punktu końcowego interfejsu API HTTP w wersji 1 różni się od starszego punktu końcowego w tych sposoby:

  • Ma ona różne wersje, a w ścieżce znajduje się /v1.
  • Ścieżka zawiera identyfikator projektu Firebase, dla którego ją w formacie /projects/myproject-ID/. Ten identyfikator jest dostępny w kartę Ogólne ustawienia projektu w konsoli Firebase.
  • Jednoznacznie określa metodę send jako :send.

Aby zaktualizować punkt końcowy serwera dla HTTP w wersji 1, dodaj te elementy do punktu końcowego w nagłówku żądania wysyłania.

Żądania HTTP przed

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

Żądania XMPP przed

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

Aktualizacja autoryzacji żądań wysyłania

Zamiast ciągu klucza serwera używanego w starszych żądaniach żądania HTTP w wersji 1 są wysyłane w wersji 1 wymaga tokena dostępu OAuth 2.0. Jeśli używasz pakietu Admin SDK wysyłania wiadomości, biblioteka zajmie się tokenem za Ciebie. Jeśli używasz uzyskać token w sposób opisany w tej sekcji i dodać go do nagłówek jako Authorization: Bearer <valid Oauth 2.0 token>.

Przed

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

Po

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

W zależności od tego, środowiska serwera, użyj kombinacji tych strategii, aby autoryzować serwer żądań do usług Firebase:

  • Domyślne uwierzytelnianie aplikacji Google (ADC)
  • Plik JSON konta usługi
  • Krótkotrwały token dostępu OAuth 2.0 pozyskany z konta usługi

Jeśli aplikacja działa w systemie Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions (w tym Cloud Functions for Firebase) używaj domyślnych danych logowania aplikacji (ADC). ADC używa istniejącej usługi domyślnej w celu uzyskania danych logowania do autoryzowania żądań, a ADC umożliwia elastyczne testy lokalne za pomocą zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS Aby zapewnić pełną automatyzację procesu autoryzacji, używaj ADC razem z bibliotekami serwera pakietu Admin SDK.

Jeśli Twoja aplikacja działa w środowisku innym niż serwer Google, musisz pobrać plik JSON konta usługi ze swojego projektu Firebase. Jeśli masz dostęp do systemu plików zawierającego pliku klucza prywatnego, można użyć zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS do autoryzowania żądań za pomocą ręcznie uzyskanych danych logowania. W przypadku braku taki dostęp do plików, musisz odnosić się do pliku konta usługi w swoim kodzie – należy robić to z najwyższą ostrożnością, ponieważ grozi to ujawnieniem Twoich danych uwierzytelniających.

Podaj dane logowania za pomocą ADC

ADC (Application Default Credentials) sprawdza Twoje dane logowania w tej kolejności:

  1. ADC sprawdza, czy zmienna środowiskowa Ustawiono: GOOGLE_APPLICATION_CREDENTIALS. Jeśli zmienna jest ustawiona, ADC używa pliku konta usługi wskazanego przez zmienną.

  2. Jeśli zmienna środowiskowa nie jest ustawiona, ADC używa domyślnego konta usługi że Compute Engine, Google Kubernetes Engine, App Engine, a Cloud Functions zapewnia aplikacje działające w tych usługach.

  3. Jeśli ADC nie może użyć tych danych, system zgłasza błąd.

Poniższy przykładowy kod pakietu Admin SDK ilustruje tę strategię. Przykład nie określa bezpośrednio danych logowania do aplikacji. ADC może jednak domyślnie znaleźć dane logowania, dopóki jest ustawiona zmienna środowiskowa; lub dopóki aplikacja działa w systemie Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions.

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(),
});

Podaj dane logowania ręcznie

Projekty Firebase obsługują Google kont usługi, które można wykorzystać do wywołania Firebase interfejsy API serwera z serwera aplikacji lub zaufanego środowiska. Jeśli tworzysz lokalnie lub lokalnie wdrażając aplikację, możesz korzystać z uzyskanych danych logowania za pośrednictwem tego konta usługi, aby autoryzować żądania serwera.

Uwierzytelnienie i autoryzacja konta usługi aby uzyskać dostęp do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON .

Aby wygenerować plik klucza prywatnego dla konta usługi:

  1. Otwórz konsolę Firebase Ustawienia > Konta usługi.

  2. Kliknij Wygeneruj nowy klucz prywatny, a następnie potwierdź, klikając Wygeneruj klucz.

  3. Bezpiecznie przechowuj plik JSON zawierający klucz.

Podczas autoryzacji za pomocą konta usługi masz 2 opcje udostępniania dane logowania do Twojej aplikacji. Możesz ustawić GOOGLE_APPLICATION_CREDENTIALS. Możesz też bezpośrednio przekazywać w kodzie ścieżkę do klucza konta usługi. Pierwsza opcja jest bezpieczniejsza i zdecydowanie zalecana.

Aby ustawić zmienną środowiskową:

Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS do ścieżki pliku JSON zawierającego klucz konta usługi. Ta zmienna ma zastosowanie tylko do bieżącej sesji powłoki, więc jeśli otworzysz w nowej sesji, ustaw zmienną ponownie.

Linux lub macOS

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

Windows

Za pomocą PowerShell:

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

Gdy wykonasz powyższe czynności, domyślne dane uwierzytelniające aplikacji (ADC) może niejawnie określić Twoje dane logowania, dzięki czemu możesz korzystać dane logowania do konta podczas testowania lub uruchamiania w środowiskach innych niż Google.

Używanie danych logowania do tworzenia tokenów dostępu

Używaj danych logowania Firebase w połączeniu z: Biblioteka uwierzytelniania Google wybierz preferowany język, aby pobrać token dostępu OAuth 2.0 o ograniczonym czasie ważności:

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

W tym przykładzie biblioteka klienta interfejsu API Google uwierzytelnia żądanie za pomocą token sieciowy JSON, czyli JWT. Więcej informacji: Tokeny sieciowe JSON.

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

Po wygaśnięciu tokena dostępu wywoływana jest metoda odświeżania tokena automatycznie pobierze zaktualizowany token dostępu.

Aby autoryzować dostęp do usługi 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>:

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

Aktualizowanie ładunku żądań wysyłania

Protokół FCM HTTP w wersji 1 wprowadza istotną zmianę w strukturze wiadomości JSON ładunek. Przede wszystkim zmiany te zapewniają prawidłową obsługę wiadomości po otrzymaniu od różnych platform klienckich; Dodatkowo dzięki tym zmianom większą elastyczność dostosowywania, czyli „zastępowanie”. pól wiadomości na platformę.

Oprócz sprawdzenia przykładów w tej sekcji zapoznaj się z artykułem Dostosuj wiadomość na różnych platformach i zapoznaj się z artykułem Dokumentacja API do uzyskania znajomości HTTP 1.

Przykład: prosta wiadomość z powiadomieniem

Oto porównanie bardzo prostego ładunku powiadomień – zawierającego dotyczy tylko pól title, body i data, prezentując podstawowe różnic w ładunkach starszych i HTTP w wersji 1.

Przed

{
  "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: zagnieżdżone dane JSON

W przeciwieństwie do starszej wersji interfejsu API do przesyłania wiadomości interfejs API HTTP w wersji 1 nie obsługuje zagnieżdżonych wartości JSON w polu data. Wymagana jest konwersja z JSON na ciąg znaków.

Przed

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

Po

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

Przykład: kierowanie na wiele platform

Aby można było włączyć kierowanie na wiele platform, starsza wersja interfejsu API wprowadziła zastąpienia z backendu. Natomiast HTTP w wersji 1 zapewnia bloki kluczy dla danej platformy, które nie wpływają na różnice nie są wyraźne i widoczne dla dewelopera. Dzięki temu możesz kierować reklamy na wiele zawsze z jednym żądaniem, co pokazano w przykładzie poniżej.

Przed

// 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ąpień platformy

Oprócz upraszczania kierowania wiadomości na wiele platform, interfejs API HTTP w wersji 1 zapewnia elastyczność w dostosowywaniu przekazu w zależności od platformy.

Przed

// 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 konkretne urządzenia za pomocą interfejsu API HTTP w wersji 1, podaj obecny token rejestracji w kluczu token zamiast klawisz to.

Przed

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

Po

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

Więcej przykładów i informacji o interfejsie API FCM HTTP v1 znajdziesz tutaj: