Przeprowadź migrację ze starszych interfejsów API FCM do protokołu HTTP v1

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:

  1. 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.

  2. 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.

  3. 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)
}
init.go

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:

  1. W konsoli Firebase otwórz Ustawienia > Konta usług .

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

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

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
messaging.py

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

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

Pyton

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

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

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: