Wysyłanie wiadomości za pomocą interfejsu FCM HTTP v1 API

Za pomocą interfejsu FCM HTTP v1 API możesz tworzyć żądania wiadomości i wysyłać je do tych typów celów:

  • Nazwa tematu
  • Warunek
  • Token rejestracji urządzenia
  • Nazwa grupy urządzeń (wycofana, zostanie usunięta 29 września 2027 r.)

Możesz wysyłać wiadomości z ładunkiem powiadomienia składającym się ze wstępnie zdefiniowanych pól, ładunkiem danych z własnych pól zdefiniowanych przez użytkownika lub wiadomości zawierające oba typy ładunku. Więcej informacji znajdziesz w sekcji Typy wiadomości.

Autoryzowanie żądań wysyłania HTTP v1

W zależności od szczegółów środowiska serwera użyj kombinacji tych strategii, aby autoryzować żądania serwera do usług Firebase:

  • domyślne uwierzytelnianie aplikacji Google (ADC),
  • plik JSON konta usługi,
  • Token dostępu OAuth 2.0 o ograniczonym czasie ważności pochodzący z konta usługi.

Jeśli aplikacja działa w Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions (w tym Cloud Functions for Firebase), użyj domyślnego uwierzytelniania aplikacji (ADC). ADC używa istniejącego domyślnego konta usługi do uzyskiwania danych uwierzytelniających na potrzeby autoryzacji żądań i umożliwia elastyczne testowanie lokalne za pomocą zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS. Aby uzyskać pełną automatyzację procesu autoryzacji, użyj ADC razem z bibliotekami serwera pakietu Admin SDK.

Jeśli aplikacja działa w środowisku serwera innego niż Google, musisz pobrać plik JSON konta usługi z projektu w Firebase. Jeśli masz dostęp do systemu plików zawierającego plik klucza prywatnego, możesz użyć zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS, aby autoryzować żądania za pomocą tych ręcznie uzyskanych danych uwierzytelniających. Jeśli nie masz dostępu do takiego pliku, musisz odwołać się do pliku konta usługi w kodzie. Należy to zrobić z zachowaniem szczególnej ostrożności ze względu na ryzyko ujawnienia danych logowania.

Podawanie danych logowania za pomocą ADC

Domyślne uwierzytelnianie aplikacji Google (ADC) sprawdza dane logowania w tej kolejności:

  1. ADC sprawdza, czy zmienna środowiskowa GOOGLE_APPLICATION_CREDENTIALS jest ustawiona. Jeśli zmienna jest ustawiona, ADC używa pliku konta usługi, na który wskazuje zmienna.

  2. Jeśli zmienna środowiskowa nie jest ustawiona, ADC używa domyślnego konta usługi, które Compute Engine, Google Kubernetes Engine, App Engine i Cloud Functions udostępniają aplikacjom działającym w tych usługach.

  3. Jeśli domyślne dane logowania aplikacji nie mogą użyć żadnych z powyższych danych logowania, system zgłasza błąd.

Tę strategię ilustruje poniższy przykładowy kod pakietu Admin SDK. W przykładzie nie określono wyraźnie danych logowania aplikacji. ADC może jednak niejawnie znaleźć dane logowania, o ile zmienna środowiskowa jest ustawiona lub aplikacja działa w 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)
}

C#

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

Podaj dane logowania ręcznie

Projekty w Firebase obsługują konta usługi Google, których możesz używać do wywoływania interfejsów Firebase Server API z serwera aplikacji lub zaufanego środowiska. Jeśli tworzysz kod lokalnie lub wdrażasz aplikację lokalnie, możesz używać danych logowania uzyskanych za pomocą tego konta usługi do autoryzowania żądań serwera.

Wszystkie konta usługi w projekcie Firebase możesz wyświetlić na karcie Ustawienia > Konta usługi.

Aby uwierzytelnić konto usługi i autoryzować je do korzystania z usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.

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

  1. W konsoli Firebase otwórz kartę 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 możliwości podania danych logowania do aplikacji. Możesz ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS lub bezpośrednio 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 ją ponownie.

Linux lub macOS

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

Windows

W PowerShell:

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

Po wykonaniu powyższych czynności domyślne uwierzytelnianie aplikacji (ADC) może pośrednio określić Twoje dane logowania, co pozwala na używanie danych logowania konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.

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

Jeśli nie używasz Firebase Admin SDK, który automatycznie obsługuje autoryzację, musisz wygenerować token dostępu i dodać go do wysyłanych żądań.

Użyj danych logowania Firebase wraz z biblioteką Google Auth w preferowanym języku, aby pobrać krótkotrwały token dostępu OAuth 2.0:

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

W tym przykładzie biblioteka klienta interfejsów API Google uwierzytelnia żądanie za pomocą tokena internetowego JSON (JWT). Więcej informacji znajdziesz w artykule na temat tokenów sieciowych 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

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

Po wygaśnięciu tokena dostępu metoda odświeżania tokena jest wywoływana automatycznie, aby pobrać zaktualizowany token 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>:

node.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;

Autoryzowanie konta usługi z innego projektu

Możesz wysyłać wiadomości w ramach jednego projektu („projektu docelowego”), używając tokena OAuth 2.0 wygenerowanego z konta usługi w innym projekcie („projekcie nadawcy”). Dzięki temu możesz scentralizować zarządzanie kontami usługi w jednym projekcie, wysyłając wiadomości w imieniu innych. Aby dowiedzieć się, jak to zrobić, wykonaj te czynności:

  1. Upewnij się, że w projekcie nadawcy jest włączony interfejs Komunikacja w chmurze Firebase (FCM) API. Sprawdź, czy jest włączona w konsoli Firebase, klikając Ustawienia > Ogólne. Następnie kliknij kartę Komunikacja w chmurze.

  2. W projekcie nadawcy utwórz konto usługi.

  3. W projekcie docelowym przypisz rolę administratora interfejsu Komunikacja w chmurze Firebase (FCM) API do adresu e-mail konta usługi. Możesz to zrobić na stronie Administracja > Uprawnienia w konsoli Google Cloud. Ta rola umożliwia kontu usługi z projektu nadawcy wysyłanie wiadomości do projektu docelowego.

  4. Wygeneruj token dostępu OAuth 2.0 dla konta usługi w projekcie nadawcy. Możesz to zrobić na jeden z tych sposobów:

    • pobieranie i używanie pliku JSON z kluczem konta usługi,
    • Używanie Workload Identity, jeśli usługa działa w Google Cloud.

  5. Użyj uzyskanego tokena dostępu w nagłówku Authorization żądania wysłania. Żądanie musi zostać wysłane do punktu końcowego HTTP v1 projektu docelowego:

      POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

Wysyłanie wiadomości na określone urządzenia

Aby wysłać powiadomienie na jedno konkretne urządzenie, przekaż token rejestracji urządzenia, jak pokazano poniżej.

REST

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

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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

Polecenie cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

W przypadku powodzenia odpowiedź interfejsu API HTTP v1 jest obiektem JSON zawierającym identyfikator wiadomości:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

Wysyłanie testowego powiadomienia za pomocą interfejsu FCM HTTP v1 API

W tej sekcji opisano, jak wysłać testowe powiadomienie za pomocą interfejsu FCM HTTP v1 API.

URL żądania HTTP

Żądanie składa się z żądania HTTP POST do określonego celu (tokenu rejestracji, tematu lub warunku) pod tym adresem URL:

POST https://fcm.googleapis.com/v1/projectId/messages:send

Przykładowy kod JSON pełnego żądania HTTP

Oto kompletny przykład pokazujący, jak opublikować powiadomienie w żądaniu POST HTTP:

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://firebase.google.com/static/images/products/cloud-messaging/cloud-messaging-hero_1x.png"
    }
  }
}

Uruchom

Kliknij Uruchom, aby wypróbować przykład w APIs Explorer.