Ten dokument opisuje sposób automatycznego odczytu i zmodyfikować zestaw parametrów i warunków w formacie JSON znanych jako Remote Config. Dzięki temu zmiany w szablonie które aplikacja kliencka może pobrać przy użyciu biblioteki klienta.
Za pomocą interfejsu API typu REST Remote Config lub Admin SDK opisane w tym przewodniku, możesz ominąć zarządzanie szablonem w konsoli Firebase, aby umożliwić bezpośrednią integrację Remote Config zmienia się w Twoje własne procesy. Na przykład Remote Config interfejs API backendu, możesz:
- Planowanie aktualizacji Remote Config. Korzystając z wywołań interfejsu API w połączeniu z zadaniem cron, możesz regularnie zmieniać wartości Remote Config.
- 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żyć Remote Config, aby promować nową funkcję w aplikacji, a potem automatycznie wyłączyć tę promocję, gdy wykryjesz, że wystarczająca liczba osób weszła w interakcję z nową funkcją.
W poniższych sekcjach tego przewodnika opisaliśmy operacje, które można wykonywać interfejsów API backendu Remote Config. Aby sprawdzić kod, który je wykonuje: za pomocą interfejsu API REST, zobacz jedną z tych przykładowych aplikacji:
- Krótkie wprowadzenie w języku Java do Zdalnej konfiguracji Firebase
- Krótkie wprowadzenie do interfejsu Node.js interfejsu Node.js Zdalnej konfiguracji Firebase
- Krótkie wprowadzenie do interfejsu API typu REST Zdalnej konfiguracji Firebase w języku Python
Modyfikowanie Zdalnej konfiguracji za pomocą pakietu Firebase Admin SDK
Admin SDK to zbiór bibliotek serwera, które umożliwiają interakcję z Firebase ze środowisk z podwyższonymi uprawnieniami. Oprócz przeprowadzania aktualizacji do Remote Config, Admin SDK umożliwia generowanie i weryfikację Tokeny uwierzytelniania Firebase, odczyt i zapis z Realtime Database itd. Więcej informacji o wymaganiach wstępnych i konfiguracji Admin SDK znajdziesz tutaj: Dodaj do serwera pakiet SDK Firebase Admin.
W typowym procesie Remote Config możesz pobrać bieżący szablon, zmodyfikować wybranych parametrów lub grup parametrów i warunków, sprawdź a następnie go opublikuj. Przed wykonaniem tych wywołań interfejsu API musisz autoryzować żądania z pakietu SDK.
Zainicjuj pakiet SDK i autoryzuj żądania do interfejsu API
Jeśli zainicjujesz Admin SDK bez parametrów, pakiet SDK użyje
Domyślne dane uwierzytelniające aplikacji Google
i odczytuje opcje ze zmiennej środowiskowej FIREBASE_CONFIG.
Jeśli zawartość zmiennej FIREBASE_CONFIG zaczyna się od {, zostanie przekształcona
analizowany jako obiekt JSON. W przeciwnym razie pakiet 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);
Pobierz bieżący szablon Zdalnej konfiguracji
Podczas pracy z Remote Config szablonami pamiętaj, że mogą one są obsługiwane i że każda z nich ma ograniczony czas życia od utworzenia do momentu zastąpienia jej aktualizacją: 90 dni (z łącznym limitem) z 300 przechowywanych wersji. Zobacz Szablony i obsługa wersji .
Możesz użyć interfejsów API backendu, aby pobrać bieżącą aktywną wersję Szablon Remote Config w formacie JSON.
Parametry i ich wartości utworzone specjalnie jako warianty w parametrze A/B Testing eksperyment nie jest uwzględniony 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());
Zmodyfikuj parametry Zdalnej konfiguracji
Możesz programowo modyfikować i dodawać parametry Remote Config oraz grup parametrów. Na przykład do dotychczasowej grupy parametrów o nazwie „nowe_menu” możesz dodać parametr, który kontroluje 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 grup oraz modyfikować wartości domyślne, wartości warunkowe i opisy. We wszystkich przypadkach musisz jednoznacznie opublikować szablon po wprowadzania zmian.
Zmodyfikuj warunki Zdalnej konfiguracji
Możesz automatycznie modyfikować i dodawać warunki Remote Config oraz wartości warunkowych. 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));
We wszystkich przypadkach musisz jednoznacznie opublikować szablon po wprowadzania zmian.
Interfejsy API backendu Remote Config zapewniają kilka warunków i porównań operatorów, których możesz użyć do zmiany działania i wyglądu aplikacji. Do więcej informacji o warunkach i operatorach obsługiwanych w przypadku tych warunków, zobacz odwołanie do wyrażeń warunkowych.
Weryfikowanie szablonu Zdalnej konfiguracji
Opcjonalnie możesz sprawdzić aktualizacje przed ich opublikowaniem w ten sposób:
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()); } }
Proces weryfikacji
sprawdza, czy nie występują błędy, takie jak zduplikowane klucze parametrów i warunków;
nieprawidłowe nazwy warunków, nieistniejące warunki lub niewłaściwie sformatowane znaczniki.
Na przykład żądanie zawierające więcej niż dozwoloną liczbę
Klucze – 2000 – zwracają komunikat o błędzie: Param count too large.
Opublikuj szablon Zdalnej konfiguracji.
Po pobraniu szablonu i poprawieniu go z uwzględnieniem pożądanego aktualizacje, możesz je opublikować. Publikowanie szablonu w sposób opisany w zastępuje cały istniejący szablon konfiguracji zaktualizowanym plikiem, nowy aktywny szablon otrzyma wersję o 1 numerze większą niż który zastąpił szablon.
W razie potrzeby możesz użyć interfejsu API REST, aby przywrócić poprzednią wersję. Aby ograniczyć ryzyko błędów aktualizacji, możesz: weryfikacji przed opublikowaniem.
Remote Config personalizacji i warunków są uwzględnione w pobranych szablonów. Pamiętaj o tych kwestiach: podczas próby opublikowania w innym projekcie:
Nie można importować personalizacji z projektu do projektu.
Jeśli na przykład w projekcie masz włączone personalizacje pobrać i edytować szablon, można go opublikować projektu, ale nie możesz go opublikować w innym projekcie, chyba że go usuniesz personalizacje z szablonu.
Warunki można importować z projektu do projektu, ale pamiętaj, że każdy określonych wartości warunkowych (np. identyfikatory aplikacji lub listy odbiorców) powinny występować w projektu docelowego przed opublikowaniem.
Jeśli np. masz parametr Remote Config, który korzysta z warunku określające wartość platformy
iOS, szablon może zostać opublikowany do innego projektu, ponieważ wartości platformy są dla każdego projektu takie same. Jeśli jednak zawiera warunek, który zależy od określonego identyfikatora aplikacji lub użytkownika odbiorcy, których nie ma w projekcie docelowym, weryfikacja się nie powiedzie.Jeśli szablon, który zamierzasz opublikować, zawiera warunki oparte na W środowisku docelowym musi być włączona funkcja Google Analytics, Analytics w projektach AI.
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 przy użyciu interfejsu API REST
W tej sekcji opisano główne funkcje
Interfejs API typu REST Remote Config w witrynie https://firebaseremoteconfig.googleapis.com.
Szczegółowe informacje znajdziesz w dokumentacji interfejsu API.
Uzyskiwanie tokena dostępu w celu uwierzytelniania i autoryzowania żądań do interfejsu API
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:
Otwórz konsolę Firebase 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 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ż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 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ą 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 = 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 wywoływana jest metoda odświeżania tokena automatycznie pobierze zaktualizowany token dostępu.
Aby autoryzować dostęp do usługi Remote Config, poproś o zakres
https://www.googleapis.com/auth/firebase.remoteconfig
Modyfikowanie szablonu Zdalnej konfiguracji
Podczas pracy z Remote Config szablonami pamiętaj, że mogą one są obsługiwane i że każda z nich ma ograniczony czas życia od utworzenia do momentu zastąpienia jej aktualizacją: 90 dni (z łącznym limitem) z 300 przechowywanych wersji. Zobacz Szablony i obsługa wersji .
Pobierz bieżący szablon Zdalnej konfiguracji
Możesz użyć interfejsów API backendu, aby pobrać bieżącą aktywną wersję Szablon Remote Config w formacie JSON.
Parametry i ich wartości utworzone specjalnie jako warianty w parametrze A/B Testing eksperyment nie jest uwzględniony 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 filename
Wywołuje ono ładunek JSON do jednego pliku, a nagłówki (wraz z Etag) do osobnego pliku.
Nieprzetworzone żą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 następujący kod JSON, wraz z osobnym nagłówkiem, który zawiera tag elektroniczny, który służy do kolejne żądanie.
Weryfikowanie szablonu Zdalnej konfiguracji
Opcjonalnie możesz sprawdzić wprowadzone zmiany przed ich opublikowaniem.
Zweryfikuj aktualizacje szablonu, dołączając do
do żądania publikacji parametru adresu URL ?validate_only=true.
W odpowiedzi kod stanu 200 i zaktualizowany tag z sufiksem -0
oznacza, że aktualizacja została zweryfikowana. Dowolna odpowiedź inna niż 200
wskazuje, że dane JSON zawierają błędy, które należy poprawić, zanim
do publikacji.
Aktualizacja szablonu Zdalnej konfiguracji
Po pobraniu szablonu i poprawieniu zawartości JSON aktualizacje, możesz je opublikować. Publikowanie szablonu w sposób opisany w zastępuje cały istniejący szablon konfiguracji zaktualizowanym plikiem, nowy aktywny szablon otrzyma wersję o 1 numerze większą niż który zastąpił szablon.
W razie potrzeby możesz użyć interfejsu API REST, aby przywrócić poprzednią wersję. Aby ograniczyć ryzyko błędów aktualizacji, możesz: weryfikacji przed opublikowaniem.
Remote Config personalizacji i warunków są uwzględnione w pobranych szablonów. Pamiętaj o tych kwestiach: podczas próby opublikowania w innym projekcie:
Nie można importować personalizacji z projektu do projektu.
Jeśli na przykład w projekcie masz włączone personalizacje pobrać i edytować szablon, można go opublikować projektu, ale nie możesz go opublikować w innym projekcie, chyba że go usuniesz personalizacje z szablonu.
Warunki można importować z projektu do projektu, ale pamiętaj, że każdy określonych wartości warunkowych (np. identyfikatory aplikacji lub listy odbiorców) powinny występować w projektu docelowego przed opublikowaniem.
Jeśli np. masz parametr Remote Config, który korzysta z warunku określające wartość platformy
iOS, szablon może zostać opublikowany do innego projektu, ponieważ wartości platformy są dla każdego projektu takie same. Jeśli jednak zawiera warunek, który zależy od określonego identyfikatora aplikacji lub użytkownika odbiorcy, których nie ma w projekcie docelowym, weryfikacja się nie powiedzie.Jeśli szablon, który zamierzasz opublikować, zawiera warunki oparte na W środowisku docelowym musi być włączona funkcja Google Analytics, Analytics w projektach AI.
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 @filename
W przypadku tego polecenia curl treść możesz określić za pomocą znaku „@” znak,
z nazwą 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
Jest to żądanie zapisu, więc funkcja ETag
zostanie zmodyfikowana przez to polecenie, a zaktualizowany tag ETag zostanie przesłany
nagłówki odpowiedzi następnego polecenia PUT.
Zmodyfikuj warunki Zdalnej konfiguracji
Możesz automatycznie modyfikować warunki Remote Config i warunkowe . W przypadku interfejsu API typu REST musisz edytować szablon bezpośrednio przed opublikowaniem szablonu.
{
"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 definiuje wartości domyślne i parametry zależne od warunków (wartości warunkowe) wartości poszczególnych parametrów. Dodaje też opcjonalny opis do każdej z nich, element; np. komentarze do kodu, są przeznaczone dla programistów i nie są wyświetlane. w aplikacji. ETag to są też udostępniane na potrzeby kontroli wersji.
Interfejsy API backendu Remote Config zapewniają kilka warunków i porównań operatorów, których możesz użyć do zmiany działania i wyglądu aplikacji. Do więcej informacji o warunkach i operatorach obsługiwanych w przypadku tych warunków, zobacz odwołanie do wyrażeń warunkowych.
Kody błędów HTTP
| Kod stanu | Znaczenie |
|---|---|
| 200 | Zaktualizowano |
| 400 | Podczas weryfikacji wystąpił błąd. Na przykład żądanie zawierające więcej niż
dozwolona liczba kluczy – 2000 – zwraca wartość 400 (Nieprawidłowe żądanie) z argumentem
komunikat o błędzie: Param count too large.
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 typu REST Firebase Remote Config nie został dodany do Twojego projektu w konsola programisty Google 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, wyślij zgłoszenie do zespołu pomocy Firebase |
Kod stanu 200 oznacza, że szablon Remote Config (parametry, wartości i warunków projektu) została zaktualizowana i jest teraz dostępna dla aplikacji używający tego projektu. Inne kody stanu wskazują, że Remote Config istniejący wcześniej szablon nadal obowiązuje.
Po przesłaniu aktualizacji szablonu otwórz konsolę Firebase, aby
sprawdź, czy zmiany są wyświetlane zgodnie z oczekiwaniami. Ma to kluczowe znaczenie, ponieważ
kolejność warunków wpływa na sposób ich oceny (pierwszy warunek,
sprawdza zastosowanie true).
Wykorzystanie ETag i wymuszone aktualizacje
Interfejs API typu REST Remote Config używa tagu encji (ETag) do zapobiegania warunkom wyścigu i pokrywających się aktualizacji zasobów. Więcej informacji o tagach ETag znajdziesz w artykule ETag – HTTP.
W przypadku interfejsu API typu REST Google zaleca zapisywanie w pamięci podręcznej
użyj parametru ETag dostarczonego w najnowszym poleceniu GET i użyj tej wartości ETag,
w nagłówku żądania If-Match podczas uruchamiania poleceń PUT. Jeśli PUT
zwraca kod stanu HTTPS 409, musisz wysłać nowe GET
w celu uzyskania nowego tagu ETag i szablonu do użycia w następnym poleceniu PUT.
Możesz obejść ETag i zapewniane przez nie zabezpieczenia,
wymusza aktualizację szablonu Remote Config w następujący sposób: If-Match: *
Nie jest to jednak zalecane, ponieważ może spowodować utratę
aktualizacje szablonu Remote Config, jeśli wielu klientów aktualizuje
Szablon Remote Config. Tego rodzaju konflikt może wystąpić, gdy
klientów używających interfejsu API albo z sprzecznymi aktualizacjami z klientów API
Firebase użytkowników konsoli.
Wskazówki dotyczące zarządzania wersjami szablonu Remote Config znajdziesz w artykule Szablony Zdalnej konfiguracji i obsługa wersji.