Z tego dokumentu dowiesz się, jak programowo odczytywać i modyfikować zbiór parametrów i warunków w formacie JSON, czyli Remote Config szablon. Dzięki temu możesz wprowadzać zmiany w szablonie na backendzie, które aplikacja kliencka może pobierać za pomocą biblioteki klienta.
Korzystając z Remote Config interfejsu REST API lub Admin SDKs opisanych w tym przewodniku, możesz pominąć zarządzanie szablonem w Firebase konsoli i bezpośrednio zintegrować zmiany Remote Config z własnymi procesami. Na przykład za pomocą interfejsów API backendu możesz:Remote Config
- Planowanie Remote Config aktualizacji. Używając wywołań interfejsu API w połączeniu z zadaniem cron, możesz regularnie zmieniać wartości Remote Config.
- Importuj wartości konfiguracji w partiach, aby sprawnie przejść z własnego systemu na Firebase Remote Config.
Używaj Remote Config z Cloud Functions for Firebase, zmieniając wartości w aplikacji na podstawie zdarzeń, które mają miejsce po stronie serwera. Możesz na przykład użyć Remote Config, aby promować nową funkcję w aplikacji, a potem automatycznie wyłączyć tę promocję, gdy zauważysz, że wystarczająca liczba osób weszła w interakcję z nową funkcją.
W sekcjach poniżej opisujemy operacje, które możesz wykonać za pomocą Remote Configinterfejsów API backendu. Aby przejrzeć kod, który wykonuje te zadania za pomocą interfejsu API REST, zapoznaj się z jedną z tych przykładowych aplikacji:
- Krótki przewodnik po interfejsie REST API Zdalnej konfiguracji Firebase w języku Java
- Krótkie wprowadzenie do interfejsu Firebase Remote Config REST API w Node.js
- Krótki przewodnik po Pythonie dotyczący API REST Zdalnej konfiguracji Firebase
Modyfikowanie Zdalnej konfiguracji za pomocą pakietu Firebase Admin SDK
Admin SDK to zestaw bibliotek serwera, które umożliwiają interakcję z Firebase w środowiskach uprzywilejowanych. Oprócz wykonywania aktualizacji Remote Config Admin SDK umożliwia generowanie i weryfikowanie tokenów uwierzytelniania Firebase, odczytywanie i zapisywanie danych z Realtime Database itp. Więcej informacji o Admin SDKwymaganiach 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ć poprawność szablonu, a następnie go opublikować. Zanim wykonasz te wywołania interfejsu API, musisz autoryzować żądania z pakietu SDK.
Inicjowanie pakietu SDK i autoryzowanie żądań interfejsu API
Gdy zainicjujesz Admin SDK bez parametrów, pakiet SDK użyje domyślnych danych logowania aplikacji Google i odczyta opcje ze zmiennej środowiskowej FIREBASE_CONFIG.
Jeśli zawartość zmiennej FIREBASE_CONFIG zaczyna się od znaku {, zostanie ona przeanalizowana jako obiekt JSON. W przeciwnym razie pakiet SDK zakłada, że ciąg znaków jest nazwą 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
Pamiętaj, że Remote Configszablony mają wersje, a każda wersja ma ograniczony okres ważności od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Więcej informacji znajdziesz w sekcji Szablony i wersje.
Za pomocą interfejsów API backendu możesz pobrać aktualną aktywną wersję szablonu Remote Config w formacie JSON.
Parametry i wartości parametrów utworzone specjalnie jako warianty w A/B Testingeksperymencie nie są uwzględniane w eksportowanych szablonach.
Aby pobrać 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());
Modyfikowanie parametrów Zdalnej konfiguracji
Możesz programowo modyfikować i dodawać parametry Remote Config oraz grupy parametrów. Na przykład do istniejącej grupy parametrów o nazwie „new_menu” możesz dodać 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.") );
Interfejs API umożliwia tworzenie nowych parametrów i grup parametrów oraz modyfikowanie wartości domyślnych, wartości warunkowych i opisów. W każdym przypadku po wprowadzeniu zmian musisz wyraźnie opublikować szablon.
Zmienianie warunków Zdalnej konfiguracji
Możesz programowo 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 backendu Remote Config udostępniają kilka warunków i operatorów porównania, których możesz używać do zmiany działania i wyglądu aplikacji. Więcej informacji o warunkach i operatorach obsługiwanych w przypadku tych warunków znajdziesz w dokumentacji wyrażeń warunkowych.
Weryfikowanie szablonu Zdalnej konfiguracji
Opcjonalnie możesz zweryfikować zmiany przed ich opublikowaniem, jak pokazano poniżej:
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()); } }
Ten proces weryfikacji sprawdza błędy, takie jak zduplikowane klucze parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki czy nieprawidłowo sformatowane tagi etag.
Na przykład żądanie zawierające więcej niż dozwolona liczba kluczy – 2000 – zwróci komunikat o błędzie Param count too large.
Opublikuj szablon Zdalnej konfiguracji.
Po pobraniu szablonu i wprowadzeniu w nim odpowiednich zmian możesz go opublikować. Opublikowanie szablonu w sposób opisany w tej sekcji zastępuje cały dotychczasowy szablon konfiguracji zaktualizowanym plikiem, a nowy aktywny szablon otrzymuje numer wersji o 1 większy od numeru szablonu, który zastąpił.
W razie potrzeby możesz użyć interfejsu REST API, aby przywrócić poprzednią wersję. Aby zmniejszyć ryzyko błędów w aktualizacji, możesz sprawdzić ją przed opublikowaniem.
Remote Config personalizacje i warunki są uwzględniane w pobranych szablonach, dlatego podczas próby opublikowania w innym projekcie należy pamiętać o tych ograniczeniach:
Personalizacji nie można importować z jednego projektu do drugiego.
Jeśli na przykład masz włączoną personalizację w projekcie, a pobierzesz i edytujesz szablon, możesz opublikować go w tym samym projekcie, ale nie w innym, chyba że usuniesz z niego personalizację.
Warunki można importować z projektu do projektu, ale pamiętaj, że przed opublikowaniem w projekcie docelowym powinny istnieć wszystkie konkretne wartości warunkowe (np. identyfikatory aplikacji lub odbiorcy).
Jeśli np. masz parametr Remote Config, który używa warunku określającego wartość platformy
iOS, szablon można opublikować w innym projekcie, ponieważ wartości platformy są takie same w każdym projekcie. Jeśli jednak zawiera warunek, który zależy od konkretnego identyfikatora aplikacji lub listy odbiorców, która nie istnieje w projekcie docelowym, weryfikacja się nie powiedzie.Jeśli szablon, który chcesz opublikować, zawiera warunki zależne od Google Analytics, w projekcie docelowym musi być włączona funkcja 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 możliwości interfejsu API typu REST Remote Config pod adresem https://firebaseremoteconfig.googleapis.com.
Szczegółowe informacje znajdziesz w dokumentacji interfejsu API.
Uzyskiwanie tokena dostępu do 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 zaufanego środowiska. Jeśli tworzysz kod 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 przyznać mu uprawnienia dostępu do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.
Aby wygenerować plik klucza prywatnego dla konta usługi:
W Firebase konsoli otwórz Ustawienia > Konta usługi.
Kliknij Wygeneruj nowy klucz prywatny, a potem 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 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 jest stosowana tylko w 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 kroków domyślne dane logowania aplikacji (ADC) będą mogły niejawnie określać Twoje dane logowania, co umożliwi Ci używanie danych logowania konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.
Użyj danych logowania Firebase wraz z biblioteką Google Auth Library w preferowanym języku, aby pobrać krótkotrwały token dostępu OAuth 2.0:
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 Google API 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();
}
Po wygaśnięciu tokena dostępu automatycznie wywoływana jest metoda odświeżania tokena, aby pobrać zaktualizowany token dostępu.
Aby autoryzować dostęp do Remote Config, poproś o zakreshttps://www.googleapis.com/auth/firebase.remoteconfig.
Modyfikowanie szablonu Zdalnej konfiguracji
Pamiętaj, że Remote Configszablony mają wersje, a każda wersja ma ograniczony okres ważności od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Więcej informacji znajdziesz w sekcji Szablony i wersje.
Pobieranie bieżącego szablonu Zdalnej konfiguracji
Za pomocą interfejsów API backendu możesz pobrać aktualną aktywną wersję szablonu Remote Config w formacie JSON.
Parametry i wartości parametrów utworzone specjalnie jako warianty w A/B Testingeksperymencie 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 zapisuje ładunek JSON w jednym pliku, a nagłówki (w tym ETag) w osobnym pliku.
Surowe żądanie HTTP
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 poniższy kod JSON wraz z osobnym nagłówkiem, który zawiera ETag używany w kolejnym żądaniu.
Weryfikowanie szablonu Zdalnej konfiguracji
Opcjonalnie możesz sprawdzić zmiany przed ich opublikowaniem.
Sprawdź aktualizacje szablonu, dodając do żądania publikacji parametr adresu URL ?validate_only=true.
W odpowiedzi kod stanu 200 i zaktualizowany tag ETag z sufiksem -0
oznaczają, że aktualizacja została zweryfikowana. Każda odpowiedź inna niż 200 oznacza, że dane JSON zawierają błędy, które musisz poprawić przed opublikowaniem.
Aktualizowanie szablonu Zdalnej konfiguracji
Po pobraniu szablonu i zmodyfikowaniu treści JSON zgodnie z potrzebnymi aktualizacjami możesz go opublikować. Opublikowanie szablonu w sposób opisany w tej sekcji zastępuje cały dotychczasowy szablon konfiguracji zaktualizowanym plikiem, a nowy aktywny szablon otrzymuje numer wersji o 1 większy od numeru szablonu, który zastąpił.
W razie potrzeby możesz użyć interfejsu REST API, aby przywrócić poprzednią wersję. Aby zmniejszyć ryzyko błędów w aktualizacji, możesz sprawdzić ją przed opublikowaniem.
Remote Config personalizacje i warunki są uwzględniane w pobranych szablonach, dlatego podczas próby opublikowania w innym projekcie należy pamiętać o tych ograniczeniach:
Personalizacji nie można importować z jednego projektu do drugiego.
Jeśli na przykład masz włączoną personalizację w projekcie, a pobierzesz i edytujesz szablon, możesz opublikować go w tym samym projekcie, ale nie w innym, chyba że usuniesz z niego personalizację.
Warunki można importować z projektu do projektu, ale pamiętaj, że przed opublikowaniem w projekcie docelowym powinny istnieć wszystkie konkretne wartości warunkowe (np. identyfikatory aplikacji lub odbiorcy).
Jeśli np. masz parametr Remote Config, który używa warunku określającego wartość platformy
iOS, szablon można opublikować w innym projekcie, ponieważ wartości platformy są takie same w każdym projekcie. Jeśli jednak zawiera warunek, który zależy od konkretnego identyfikatora aplikacji lub listy odbiorców, która nie istnieje w projekcie docelowym, weryfikacja się nie powiedzie.Jeśli szablon, który chcesz opublikować, zawiera warunki zależne od Google Analytics, w projekcie docelowym musi być włączona funkcja 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 przypadku tego polecenia curl możesz określić treść, używając znaku „@” i nazwy pliku.
Surowe żą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 jest modyfikowane przez to polecenie, a zaktualizowany tag ETag jest podawany w nagłówkach odpowiedzi następnego polecenia PUT.
Zmienianie warunków Zdalnej konfiguracji
Możesz programowo modyfikować Remote Config warunki 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."
}
}
}Powyższe modyfikacje najpierw definiują zestaw warunków, a następnie wartości domyślne i wartości parametrów oparte 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. Na potrzeby kontroli wersji podawany jest też ETag.
Interfejsy API backendu Remote Config udostępniają kilka warunków i operatorów porównania, których możesz używać do zmiany działania i wyglądu aplikacji. Więcej informacji o warunkach i operatorach obsługiwanych w przypadku tych warunków znajdziesz w dokumentacji wyrażeń 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 niż dozwolona liczba kluczy – 2000 – zwróci kod błędu 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 Cloud Developer Console). |
| 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, wyślij zgłoszenie do zespołu pomocy Firebase |
Kod stanu 200 oznacza, że Remote Configszablon (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 Remote Configwcześniej istniejący szablon nadal obowiązuje.
Po przesłaniu aktualizacji szablonu otwórz Firebase konsolę, aby sprawdzić, czy zmiany są widoczne zgodnie z oczekiwaniami. Jest to bardzo ważne, ponieważ kolejność warunków wpływa na sposób ich oceny (zastosowanie ma pierwszy warunek, który daje wynik true).
Użycie tagu ETag i wymuszone aktualizacje
Interfejs API REST Remote Config używa tagu encji (ETag), aby zapobiegać sytuacjom wyścigu i nakładającym się aktualizacjom zasobów. Więcej informacji o tagach ETag znajdziesz w artykule ETag – HTTP.
W przypadku interfejsu REST API Google zaleca zapisywanie w pamięci podręcznej znacznika ETag podanego przez ostatnie polecenie GET i używanie tej wartości znacznika ETag w nagłówku żądania If-Match podczas wydawania poleceń PUT. Jeśli PUTpolecenie zwróci kod stanu HTTPS 409, wydaj nowe polecenie GET, aby uzyskać nowy tag ETag i szablon do użycia z następnym poleceniem PUT.
Możesz obejść tag ETag i ochronę, jaką zapewnia, wymuszając aktualizację szablonu Remote Config w ten sposób: If-Match: *
Nie zalecamy jednak tego podejścia, ponieważ w przypadku aktualizowania szablonu Remote Config przez wielu klientów może to spowodować utratę aktualizacji szablonu Remote Config. Tego rodzaju konflikt może wystąpić w przypadku wielu klientów korzystających z interfejsu API lub w przypadku sprzecznych aktualizacji od klientów interfejsu API i użytkowników konsoli Firebase.
Wskazówki dotyczące zarządzania wersjami szablonów Remote Config znajdziesz w artykule Szablony i wersje Remote Config.