W tym dokumencie opisano, jak odczytywać i modyfikować za pomocą kodu zestaw parametrów i warunków w formacie JSON, czyli tzw. szablon Remote Config. Dzięki temu możesz wprowadzić zmiany w szablonie backendu, które aplikacja kliencka może pobrać za pomocą biblioteki klienta.
Korzystając z interfejsu Remote Config REST API lub Admin SDK opisanych w tym przewodniku, możesz pominąć zarządzanie szablonem w konsoli Firebase, aby bezpośrednio zintegrować zmiany Remote Config ze swoimi procesami. Na przykład za pomocą interfejsów API zaplecza Remote Config możesz:
- Planowanie aktualizacji Remote Config. Za pomocą wywołań interfejsu API w połączeniu z zadaniem crona możesz zmieniać wartości Remote Config według regularnego harmonogramu.
- Zbiorczy import wartości konfiguracyjnych importu, aby umożliwić sprawne przejście z własnego zastrzeżonego systemu na system Firebase Remote Config.
Używając Remote Config z zasadą Cloud Functions for Firebase, zmieniaj wartości w aplikacji na podstawie zdarzeń zachodzących po stronie serwera. Możesz na przykład używać Remote Config do promowania nowej funkcji w aplikacji, a potem automatycznie wyłączać tę promocję, gdy wykryjesz, że wystarczająca liczba osób skorzystała z tej funkcji.
W poniższych sekcjach tego przewodnika opisaliśmy operacje, które możesz wykonywać za pomocą interfejsów API backendu Remote Config. Aby zapoznać się z kodem, który wykonuje te zadania za pomocą interfejsu API REST, zapoznaj się z jedną z tych przykładowych aplikacji:
- Krótki przewodnik po interfejsie Firebase Remote Config REST API w Javie
- Krótki przewodnik po interfejsie Firebase Remote Config REST API w Node.js
- Krótki przewodnik po interfejsie API Zdalnej konfiguracji Firebase w Pythonie
Modyfikowanie Zdalnej konfiguracji za pomocą pakietu Firebase Admin SDK
Admin SDK to zestaw bibliotek serwera, które umożliwiają interakcję z Firebase z prywatnych środowisk. Oprócz wykonywania operacji aktualizacji w Remote Config usługa Admin SDK umożliwia też generowanie i weryfikowanie tokenów uwierzytelniania Firebase, odczytywanie i zapisywanie danych z Realtime Database itp. Więcej informacji o Admin SDK wymaganiach wstępnych i konfiguracji znajdziesz w artykule Dodawanie pakietu Firebase Admin SDK do serwera.
W typowym procesie Remote Config możesz pobrać bieżący szablon, zmodyfikować niektóre parametry lub grupy parametrów i warunki, sprawdzić szablon, a następnie go opublikować. Zanim wykonasz te wywołania interfejsu API, musisz autoryzować żądania z pakietu SDK.
Zainicjuj pakiet SDK i autoryzuj żądania do interfejsu API
Gdy zainicjujesz Admin SDK bez parametrów, pakiet SDK używa domyślnych danych logowania aplikacji Google i odczytuje opcje ze zmiennej środowiskowej FIREBASE_CONFIG.
Jeśli zawartość zmiennej FIREBASE_CONFIG zaczyna się od {, zostanie ona przetworzona jako obiekt JSON. W przeciwnym razie SDK zakłada, że ciąg znaków to nazwa pliku JSON zawierającego opcje.
Przykład:
Node.js
const admin = require('firebase-admin'); admin.initializeApp();
Java
FileInputStream serviceAccount = new FileInputStream("service-account.json"); FirebaseOptions options = FirebaseOptions.builder() .setCredentials(GoogleCredentials.fromStream(serviceAccount)) .build(); FirebaseApp.initializeApp(options);
Pobieranie bieżącego szablonu Zdalnej konfiguracji
Podczas pracy z szablonami Remote Config pamiętaj, że są one wersjonowane i że każda wersja ma ograniczony czas istnienia od momentu jej utworzenia do momentu zastąpienia przez aktualizację: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Więcej informacji znajdziesz w artykule Szablony i obsługa wersji.
Za pomocą interfejsów API backendu możesz pobrać bieżącą aktywną wersję szablonu Remote Config w formacie JSON.
Parametry i ich wartości utworzone specjalnie jako warianty w eksperymencie A/B Testing nie są uwzględniane w eksportowanych szablonach.
Aby uzyskać szablon:
Node.js
function getTemplate() { var config = admin.remoteConfig(); config.getTemplate() .then(function (template) { console.log('ETag from server: ' + template.etag); var templateStr = JSON.stringify(template); fs.writeFileSync('config.json', templateStr); }) .catch(function (err) { console.error('Unable to get template'); console.error(err); }); }
Java
Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get(); // See the ETag of the fetched template. System.out.println("ETag from server: " + template.getETag());
Zmodyfikuj parametry Zdalnej konfiguracji
Możesz programowo modyfikować i dodawać parametry Remote Config oraz grupy parametrów. Możesz np. dodać do istniejącej grupy parametrów o nazwie „new_menu” parametr, który będzie kontrolować wyświetlanie informacji sezonowych:
Node.js
function addParameterToGroup(template) { template.parameterGroups['new_menu'].parameters['spring_season'] = { defaultValue: { useInAppDefault: true }, description: 'spring season menu visibility.', }; }
Java
template.getParameterGroups().get("new_menu").getParameters() .put("spring_season", new Parameter() .setDefaultValue(ParameterValue.inAppDefault()) .setDescription("spring season menu visibility.") );
Umożliwia on tworzenie nowych parametrów i grup parametrów oraz modyfikowanie wartości domyślnych i warunkowych oraz opisów. W każdym przypadku po wprowadzeniu zmian musisz wyraźnie opublikować szablon.
Zmodyfikuj warunki Zdalnej konfiguracji
Za pomocą kodu możesz modyfikować i dodawać Remote Config warunki oraz wartości warunkowe. Aby na przykład dodać nowy warunek:
Node.js
function addNewCondition(template) { template.conditions.push({ name: 'android_en', expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']', tagColor: 'BLUE', }); }
Java
template.getConditions().add(new Condition("android_en", "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));
W każdym przypadku po wprowadzeniu zmian musisz wyraźnie opublikować szablon.
Interfejsy API zaplecza Remote Config udostępniają kilka warunków i operatorów porównań, których możesz używać do zmiany działania i wyglądu aplikacji. Więcej informacji o warunkach i operatorach obsługiwanych przez te warunki znajdziesz w przewodniku po wyrażeniach warunkowych.
Weryfikowanie szablonu Zdalnej konfiguracji
Opcjonalnie możesz zweryfikować aktualizacje przed ich opublikowaniem:
Node.js
function validateTemplate(template) { admin.remoteConfig().validateTemplate(template) .then(function (validatedTemplate) { // The template is valid and safe to use. console.log('Template was valid and safe to use'); }) .catch(function (err) { console.error('Template is invalid and cannot be published'); console.error(err); }); }
Java
try { Template validatedTemplate = FirebaseRemoteConfig.getInstance() .validateTemplateAsync(template).get(); System.out.println("Template was valid and safe to use"); } catch (ExecutionException e) { if (e.getCause() instanceof FirebaseRemoteConfigException) { FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause(); System.out.println("Template is invalid and cannot be published"); System.out.println(rcError.getMessage()); } }
W ramach tego procesu weryfikacji sprawdzane są błędy takie jak zduplikowane klucze parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki albo nieprawidłowo sformatowane etagi.
Na przykład żądanie zawierające więcej niż dozwoloną liczbę kluczy (2000) zwróci komunikat o błędzie Param count too large.
Publikowanie szablonu Zdalnej konfiguracji
Po pobraniu szablonu i wprowadzeniu w nim odpowiednich zmian możesz go opublikować. Opublikowanie szablonu w sposób opisany w tej sekcji spowoduje zastąpienie całego istniejącego szablonu konfiguracji zaktualizowanym plikiem, a do nowego aktywnego szablonu zostanie przypisany numer wersji o 1 numerze wyższy niż szablon, który zastąpił.
W razie potrzeby możesz użyć interfejsu REST API, aby przywrócić poprzednią wersję. Aby zmniejszyć ryzyko wystąpienia błędów w aktualizacji, możesz potwierdzić ją przed opublikowaniem.
Remote ConfigW pobieranych szablonach uwzględniono personalizację i warunki, dlatego podczas próby opublikowania w innym projekcie należy wziąć pod uwagę te ograniczenia:
Personalizacji nie można importować z jednego projektu do drugiego.
Jeśli na przykład masz w projekcie włączoną personalizację i pobierasz oraz edytujesz szablon, możesz go opublikować w tym samym projekcie, ale nie możesz opublikować go w innym projekcie, chyba że usuniesz z niego personalizację.
Warunki można importować z jednego projektu do drugiego, ale pamiętaj, że przed opublikowaniem w projekcie docelowym powinny znajdować się wszystkie konkretne wartości warunkowe (np. identyfikatory aplikacji lub listy odbiorców).
Jeśli na przykład masz parametr Remote Config korzystający z warunku, który określa wartość platformy równą
iOS, szablon można opublikować w innym projekcie, ponieważ wartości platformy są takie same dla każdego projektu. Jeśli jednak zawiera warunek, który zależy od określonego identyfikatora aplikacji lub grupy odbiorców, którego nie ma w projekcie docelowym, weryfikacja się nie powiedzie.Jeśli szablon, który chcesz opublikować, zawiera warunki korzystające z danych Google Analytics, w projekcie docelowym musi być włączona zasada Analytics.
Node.js
function publishTemplate() { var config = admin.remoteConfig(); var template = config.createTemplateFromJSON( fs.readFileSync('config.json', 'UTF8')); config.publishTemplate(template) .then(function (updatedTemplate) { console.log('Template has been published'); console.log('ETag from server: ' + updatedTemplate.etag); }) .catch(function (err) { console.error('Unable to publish template.'); console.error(err); }); }
Java
try { Template publishedTemplate = FirebaseRemoteConfig.getInstance() .publishTemplateAsync(template).get(); System.out.println("Template has been published"); // See the ETag of the published template. System.out.println("ETag from server: " + publishedTemplate.getETag()); } catch (ExecutionException e) { if (e.getCause() instanceof FirebaseRemoteConfigException) { FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause(); System.out.println("Unable to publish template."); System.out.println(rcError.getMessage()); } }
Modyfikowanie Zdalnej konfiguracji za pomocą interfejsu API REST
W tej sekcji opisujemy główne funkcje interfejsu API REST Remote Config w https://firebaseremoteconfig.googleapis.com.
Pełne informacje znajdziesz w dokumentacji interfejsu API.
Uzyskiwanie tokena dostępu w celu uwierzytelniania i autoryzowania żądań do interfejsu API
Projekty Firebase obsługują konta usługi Google, których możesz używać do wywoływania interfejsów API serwera Firebase z serwera aplikacji lub z zaufanego środowiska. Jeśli kod tworzysz lokalnie lub wdrażasz aplikację lokalnie, możesz użyć danych logowania uzyskanych za pomocą tego konta usługi, aby autoryzować żądania serwera.
Aby uwierzytelnić konto usługi i zezwolić mu na dostęp do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.
Aby wygenerować plik klucza prywatnego dla konta usługi:
W konsoli Firebase otwórz Ustawienia > Konta usługi.
Kliknij Wygeneruj nowy klucz prywatny, a następnie potwierdź, klikając Wygeneruj klucz.
Bezpiecznie przechowuj plik JSON zawierający klucz.
Podczas autoryzacji za pomocą konta usługi masz 2 możliwości przekazania danych logowania do aplikacji. Możesz ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS lub w kodzie wyraźnie podać ścieżkę do klucza konta usługi. 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ę, musisz ponownie ustawić zmienną.
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"
Gdy wykonasz powyższe czynności, domyślne dane uwierzytelniające aplikacji (ADC) będą mogły niejawnie określić Twoje dane logowania. Dzięki temu możesz używać danych logowania do konta usługi podczas testowania lub uruchamiania aplikacji w środowiskach innych niż Google.
Użyj danych logowania Firebase w połączeniu z biblioteką uwierzytelniania Google w wybranym języku, aby pobrać token dostępu OAuth 2.0 o krótkim czasie ważności:
Node.js
function getAccessToken() {
return admin.credential.applicationDefault().getAccessToken()
.then(accessToken => {
return accessToken.access_token;
})
.catch(err => {
console.error('Unable to get access token');
console.error(err);
});
}
W tym przykładzie biblioteka klienta interfejsu API Google uwierzytelnia żądanie za pomocą tokena sieciowego JSON (JWT). Więcej informacji znajdziesz w artykule Tokeny sieciowe JSON.
Python
def _get_access_token():
"""Retrieve a valid access token that can be used to authorize requests.
:return: Access token.
"""
credentials = ServiceAccountCredentials.from_json_keyfile_name(
'service-account.json', SCOPES)
access_token_info = credentials.get_access_token()
return access_token_info.access_token
Java
public static String getAccessToken() throws IOException {
GoogleCredentials googleCredentials = GoogleCredentials
.fromStream(new FileInputStream("service-account.json"))
.createScoped(Arrays.asList(SCOPES));
googleCredentials.refreshAccessToken();
return googleCredentials.getAccessToken().getTokenValue();
}
Gdy token dostępu wygaśnie, metoda odświeżania tokena zostanie wywołana automatycznie, aby pobrać zaktualizowany token dostępu.
Aby autoryzować dostęp do Remote Config, poproś o zakres https://www.googleapis.com/auth/firebase.remoteconfig.
Modyfikowanie szablonu Zdalnej konfiguracji
Podczas pracy z szablonami Remote Config pamiętaj, że są one wersjonowane i że każda wersja ma ograniczony czas istnienia od momentu jej utworzenia do momentu zastąpienia przez aktualizację: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Więcej informacji znajdziesz w artykule Szablony i obsługa wersji.
Pobierz bieżący szablon Zdalnej konfiguracji
Za pomocą interfejsów API backendu możesz pobrać bieżącą aktywną wersję szablonu Remote Config w formacie JSON.
Parametry i ich wartości utworzone specjalnie jako warianty w eksperymencie A/B Testing nie są uwzględniane w eksportowanych szablonach.
Użyj tych poleceń:
cURL
curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filenameTo polecenie wyprowadza ładunek JSON do jednego pliku, a nagłówki (w tym Etag) do osobnego pliku.
Żądanie HTTP w postaci zwykłego tekstu
Host: firebaseremoteconfig.googleapis.com GET /v1/projects/my-project-id/remoteConfig HTTP/1.1 Authorization: Bearer token Accept-Encoding: gzip
To wywołanie interfejsu API zwraca następujący ciąg JSON-a wraz z osobnym nagłówkiem zawierającym eTag, którego używasz w kolejnych żądaniach.
Weryfikowanie szablonu Zdalnej konfiguracji
Opcjonalnie możesz sprawdzić wprowadzone zmiany przed ich opublikowaniem.
Sprawdź poprawność zmian w szablonie, dodając do żądania publikacji parametr URL ?validate_only=true.
W odpowiedzi kod stanu 200 i zaktualizowany tag identyfikatora z sufiksem -0 oznaczają, że aktualizacja została pomyślnie zweryfikowana. Każda odpowiedź inna niż 200 wskazuje, że dane JSON zawierają błędy, które należy poprawić przed opublikowaniem.
Aktualizacja szablonu Zdalnej konfiguracji
Po pobraniu szablonu i zmodyfikowaniu zawartości pliku JSON zgodnie z pożądanymi zmianami możesz go opublikować. Opublikowanie szablonu zgodnie z opisem w tej sekcji powoduje zastąpienie całego dotychczasowego szablonu konfiguracji zaktualizowanym plikiem, a nowemu aktywnemu szablonowi zostanie przypisany numer wersji o jeden wyższy niż numer wersji zastępowanego szablonu.
W razie potrzeby możesz użyć interfejsu REST API, aby przywrócić poprzednią wersję. Aby zmniejszyć ryzyko błędów podczas aktualizacji, możesz przeprowadzić weryfikację przed opublikowaniem.
Remote ConfigW pobieranych szablonach uwzględniono personalizację i warunki, dlatego podczas próby opublikowania w innym projekcie należy wziąć pod uwagę te ograniczenia:
Personalizacji nie można importować z jednego projektu do drugiego.
Jeśli na przykład masz w projekcie włączoną personalizację i pobierasz oraz edytujesz szablon, możesz go opublikować w tym samym projekcie, ale nie możesz opublikować go w innym projekcie, chyba że usuniesz z niego personalizację.
Warunki można importować z jednego projektu do drugiego, ale pamiętaj, że przed opublikowaniem w projekcie docelowym powinny znajdować się wszystkie konkretne wartości warunkowe (np. identyfikatory aplikacji lub listy odbiorców).
Jeśli na przykład masz parametr Remote Config korzystający z warunku, który określa wartość platformy równą
iOS, szablon można opublikować w innym projekcie, ponieważ wartości platformy są takie same dla każdego projektu. Jeśli jednak zawiera warunek, który zależy od określonego identyfikatora aplikacji lub grupy odbiorców, którego nie ma w projekcie docelowym, weryfikacja się nie powiedzie.Jeśli szablon, który chcesz opublikować, zawiera warunki korzystające z danych Google Analytics, w projekcie docelowym musi być włączona zasada Analytics.
cURL
curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filenameW tym poleceniu curl możesz określić treść, używając znaku „@” i nazwy pliku.
Nieprzetworzone żądanie HTTP
Host: firebaseremoteconfig.googleapis.com PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1 Content-Length: size Content-Type: application/json; UTF8 Authorization: Bearer token If-Match: expected ETag Accept-Encoding: gzip JSON_HERE
Ponieważ jest to żądanie zapisu, pole ETag zostaje zmodyfikowane przez to polecenie, a zaktualizowany tag ETag jest podawany w nagłówkach odpowiedzi kolejnego polecenia PUT.
Zmienianie warunków Zdalnej konfiguracji
Możesz programowo modyfikować warunki Remote Config i wartości warunkowe. W przypadku interfejsu REST API musisz bezpośrednio edytować szablon, aby zmodyfikować warunki przed jego opublikowaniem.
{
"conditions": [{
"name": "android_english",
"expression": "device.os == 'android' && device.country in ['us', 'uk']",
"tagColor": "BLUE"
}, {
"name": "tenPercent",
"expression": "percent <= 10",
"tagColor": "BROWN"
}],
"parameters": {
"welcome_message": {
"defaultValue": {
"value": "Welcome to this sample app"
},
"conditionalValues": {
"tenPercent": {
"value": "Welcome to this new sample app"
}
},
"description": "The sample app's welcome message"
},
"welcome_message_caps": {
"defaultValue": {
"value": "false"
},
"conditionalValues": {
"android_english": {
"value": "true"
}
},
"description": "Whether the welcome message should be displayed in all capital letters."
}
}
}Opisane wyżej modyfikacje najpierw definiują zestaw warunków, a następnie wartości domyślne i wartości parametrów opartych na warunkach (wartości warunkowe) dla każdego parametru. Dodaje też opcjonalny opis każdego elementu. Podobnie jak komentarze do kodu, są one przeznaczone dla deweloperów i nie są wyświetlane w aplikacji. W celu kontroli wersji jest też dodawany tag E.
Interfejsy API zaplecza Remote Config udostępniają kilka warunków i operatorów porównań, których możesz używać do zmiany działania i wyglądu aplikacji. Więcej informacji o warunkach i operatorach obsługiwanych przez te warunki znajdziesz w przewodniku po wyrażeniach warunkowych.
Kody błędów HTTP
| Kod stanu | Znaczenie |
|---|---|
| 200 | Zaktualizowano |
| 400 | Wystąpił błąd weryfikacji. Na przykład żądanie zawierające więcej kluczy niż dozwolone (2000) zwróciłoby wartość 400 (Nieprawidłowe żądanie) z komunikatem o błędzie Param count too large.
Ten kod stanu HTTPS może też wystąpić w tych 2 sytuacjach:
|
| 401 | Wystąpił błąd autoryzacji (nie podano tokena dostępu lub interfejs API REST Firebase Remote Config nie został dodany do projektu w konsoli administracyjnej Cloud) |
| 403 | Wystąpił błąd uwierzytelniania (podano nieprawidłowy token dostępu) |
| 500 | Wystąpił błąd wewnętrzny. Jeśli wystąpi ten błąd, złóż zgłoszenie do zespołu pomocy Firebase. |
Kod stanu 200 oznacza, że szablon Remote Config (parametry, wartości i warunki projektu) został zaktualizowany i jest teraz dostępny dla aplikacji, które korzystają z tego projektu. Inne kody stanu wskazują, że wcześniej istniejący szablon Remote Confignadal obowiązuje.
Po przesłaniu aktualizacji szablonu otwórz konsolę Firebase, aby sprawdzić, czy zmiany są wyświetlane zgodnie z oczekiwaniami. Jest to bardzo ważne, ponieważ kolejność warunków wpływa na sposób ich oceny (w efekcie obowiązuje pierwszy warunek, który zostanie spełniony).true
Używanie e-tagów i wymuszanie aktualizacji
Interfejs API REST Remote Config używa tagu elementu (ETag), aby zapobiegać sytuacjom wyścigu i nakładaniu się aktualizacji zasobów. Więcej informacji o tagach ETag znajdziesz w artykule ETag – HTTP.
W przypadku interfejsu API REST Google zaleca zapisywanie w pamięci podręcznej parametru ETag podanego w najnowszym poleceniu GET i używanie tej wartości ETag w nagłówku żądania If-Match podczas uruchamiania poleceń PUT. Jeśli polecenie PUT zwraca kod stanu HTTPS 409, musisz wydać nowe polecenie GET, aby uzyskać nowy tag ETag i szablon do użycia w kolejnych poleceniach PUT.
Możesz obejść tag ETag i zapewnianą przez niego ochronę, wymuszając aktualizację szablonu Remote Config w ten sposób: If-Match: *Nie zalecamy jednak tego podejścia, ponieważ może ono spowodować utratę aktualizacji szablonu Remote Config, jeśli wielu klientów aktualizuje szablon Remote Config. Taki konflikt może wystąpić w przypadku wielu klientów korzystających z interfejsu API lub sprzecznych aktualizacji ze strony klientów interfejsu API i użytkowników konsoli Firebase.
Wskazówki dotyczące zarządzania wersjami Remote Config szablonów znajdziesz w artykule Szablony konfiguracji zdalnej i wersjonowanie.