W tym dokumencie opisano, jak odczytywać i modyfikować za pomocą kodu zbiór parametrów i warunków w formacie JSON, czyli szablon 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 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 funkcji Remote Config w komponencie Cloud Functions for Firebase, aby zmieniać wartości w aplikacji na podstawie zdarzeń występują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 następnych sekcjach tego przewodnika opisujemy operacje, które możesz wykonywać za pomocą interfejsów backendowych Remote Config. Aby sprawdzić kod, który je wykonuje: za pomocą interfejsu API REST, zobacz jedną z tych przykładowych aplikacji:
- Krótki przewodnik po interfejsie Firebase Remote Config REST API w Javie
- 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 zestaw bibliotek serwera, które umożliwiają interakcję z Firebase z prywatnych środowisk. 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 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ć szablon, a następnie go opublikować. Przed wykonaniem tych wywołań interfejsu API musisz autoryzować żądania z pakietu SDK.
Zainicjuj pakiet SDK i autoryzuj żądania do interfejsu API
Gdy inicjujesz Admin SDK bez parametrów, pakiet SDK używa domyślnych danych logowania aplikacji Google i odczytuje opcje z zmiennej środowiskowej FIREBASE_CONFIG.
Jeśli zawartość zmiennej FIREBASE_CONFIG zaczyna się od {, zostanie zanalizowana 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 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 wersje.
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 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());Modyfikowanie parametrów Zdalnej konfiguracji
Możesz je modyfikować i dodawać za pomocą kodu oraz dodawać grupy 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 i ich grup oraz modyfikowanie wartości domyślnych, wartości warunkowych i opisów. 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));W każdym przypadku po wprowadzeniu zmian musisz wyraźnie opublikować szablon.
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());
}
}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.
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 REST API, 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 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 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 elemencie Google Analytics, w projekcie docelowym musisz włączyć element 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 opisano główne możliwości interfejsu API REST Remote Config (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 z 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.
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ć 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
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) 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.
Aby pobrać krótkotrwały token dostępu OAuth 2.0, użyj danych logowania Firebase wraz z biblioteką Google Auth Library w preferowanym języku:
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. Więcej informacji znajdziesz w artykule Szablony i wersje.
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 jako warianty w eksperymencie A/B Testing nie są uwzględniane w wyeksportowanych 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 ciąg JSON-a wraz z osobnym nagłówkiem zawierającym eTag, którego używasz w kolejnych żądaniach.
Weryfikacja szablonu Zdalnej konfiguracji
Opcjonalnie możesz sprawdzić wprowadzone zmiany przed ich opublikowaniem.
Sprawdź zmiany w szablonie, dodając do żądania publikacji parametr ?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.
Aktualizowanie 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 o jeden większy niż ten, który zastąpił.
W razie potrzeby możesz użyć interfejsu API REST, 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:
Nie można importować personalizacji z projektu do projektu.
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 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 tym poleceniu curl możesz określić zawartość, używając znaku „@”, a następnie nazwy pliku.
Żądanie HTTP w postaci zwykłego tekstu
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 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 każdego elementu. Podobnie jak komentarze do kodu, są one przeznaczone dla dewelopera i nie są wyświetlane w aplikacji. W celu kontroli wersji jest też dodawany tag E.
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 | Wystąpił błąd weryfikacji. 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 ten błąd wystąpi, 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 Remote Config istniejący wcześniej szablon nadal obowiązuje.
Po przesłaniu aktualizacji szablonu otwórz konsolę Firebase, aby sprawdzić, czy zmiany są widoczne zgodnie z oczekiwaniami. Ma to kluczowe znaczenie, ponieważ
kolejność warunków wpływa na sposób ich oceny (pierwszy warunek,
sprawdza zastosowanie 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 Tag 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ę
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 szablonu Remote Config znajdziesz w artykule Szablony Zdalnej konfiguracji i obsługa wersji.