Catch up on everthing we announced at this year's Firebase Summit. Learn more

Programowa modyfikacja Zdalnej konfiguracji

Dokument ten opisuje w jaki sposób można programowo odczytać i zmodyfikować zestaw w formacie JSON parametrów i warunków znanych jako Remote Config szablonu . Dzięki temu możesz wprowadzać zmiany szablonu w zapleczu, które aplikacja kliencka może pobrać przy użyciu biblioteki klienta.

Korzystanie z Remote Config REST API lub Admin SDK opisanych w tym przewodniku, można obwodnicy zarządzania szablon w konsoli Firebase bezpośrednio zintegrować Remote Config zmienia się własnymi procesami. Na przykład za pomocą interfejsów API backendu Remote Config możesz:

  • Planowanie zdalnej aktualizacji config. Używając wywołań API w połączeniu z zadaniem cron, możesz regularnie zmieniać wartości Zdalnej konfiguracji.
  • Batch import wartości konfiguracyjne w celu przejścia efektywnie z własnego autorskiego systemu do Firebase Remote Config.
  • Użyj funkcji Remote Config z Chmura Firebase, zmieniając wartości w swojej aplikacji w oparciu o zdarzenia, które dzieją się po stronie serwera. Na przykład możesz użyć Zdalnej konfiguracji, aby promować nową funkcję w swojej aplikacji, a następnie automatycznie wyłączyć tę promocję po wykryciu wystarczającej liczby osób, która weszła w interakcję z nową funkcją.

    Diagram przedstawiający interakcję backendu Remote Config z niestandardowymi narzędziami i serwerami

W poniższych sekcjach tego przewodnika opisano operacje, które można wykonać za pomocą interfejsów API zaplecza Remote Config. Aby przejrzeć kod, który wykonuje te zadania za pośrednictwem interfejsu API REST, zobacz jedną z tych przykładowych aplikacji:

Modyfikuj Zdalną konfigurację za pomocą pakietu Firebase Admin SDK

Admin SDK to zestaw bibliotek serwerowych, które umożliwiają interakcję z Firebase z uprzywilejowanych środowisk. Oprócz przeprowadzania aktualizacji Zdalnej konfiguracji pakiet Admin SDK umożliwia generowanie i weryfikację tokenów uwierzytelniania Firebase, odczytywanie i zapisywanie z Bazy danych czasu rzeczywistego itd. Aby dowiedzieć się więcej na temat warunków Admin SDK i konfiguracji, patrz Dodawanie Firebase Admin SDK do serwera .

W typowym przepływie Zdalnej konfiguracji można uzyskać bieżący szablon, zmodyfikować niektóre parametry lub grupy parametrów i warunki, sprawdzić poprawność szablonu, a następnie go opublikować. Przed wykonaniem tych wywołań API musisz autoryzować żądania z SDK.

Zainicjuj SDK i autoryzuj żądania API

Podczas inicjalizacji Admin SDK bez parametrów, SDK wykorzystuje Google domyślną aplikacją Poświadczenia i czyta opcje z FIREBASE_CONFIG zmiennej środowiskowej. Jeśli zawartość FIREBASE_CONFIG zmiennej zaczyna się od { będzie analizowany jako obiekt JSON. W przeciwnym razie zestaw SDK zakłada, że ​​ciąg jest nazwą pliku JSON zawierającego opcje.

Na przykład:

Node.js

const admin = require('firebase-admin');
admin.initializeApp();

Jawa

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

Pobierz aktualny szablon zdalnej konfiguracji

Podczas pracy z szablonami Zdalnej konfiguracji należy pamiętać, że są one wersjonowane oraz że każda wersja ma ograniczony czas życia od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Zobacz Szablony i wersjonowania , aby uzyskać więcej informacji.

Możesz użyć interfejsów API zaplecza, aby pobrać bieżącą aktywną wersję szablonu Zdalnej konfiguracji w formacie JSON. 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);
      });
}

Jawa

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żna programowo modyfikować i dodawać parametry i grupy parametrów Zdalnej konfiguracji. Na przykład, do istniejącej grupy parametrów o nazwie "nowe_menu" możesz dodać parametr kontrolujący wyświetlanie informacji sezonowych:

Node.js

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

Jawa

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 lub modyfikowanie wartości domyślnych, wartości warunkowych i opisów. We wszystkich przypadkach musisz jawnie opublikować szablon po dokonaniu modyfikacji.

Zmodyfikuj warunki zdalnej konfiguracji

Możesz programowo modyfikować i dodawać warunki i wartości warunkowe Zdalnej konfiguracji. Na przykład, aby 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',
  });
}

Jawa

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

We wszystkich przypadkach musisz jawnie opublikować szablon po dokonaniu modyfikacji.

Interfejsy API zaplecza Zdalnej konfiguracji udostępniają kilka warunków i operatorów porównania, których można użyć do zmiany zachowania i wyglądu aplikacji. Aby dowiedzieć się więcej na temat warunków i operatorów obsługiwanych dla tych warunków, zobacz warunkową odniesienie ekspresji .

Sprawdź poprawność szablonu Zdalnej konfiguracji

Opcjonalnie możesz sprawdzić poprawność aktualizacji przed ich opublikowaniem, jak pokazano:

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);
      });
}

Jawa

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 sprawdzania poprawności sprawdza, czy nie ma błędów, takich jak zduplikowane klucze parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki lub niepoprawnie sformatowane tagi etag. Na przykład, wniosek zawierający więcej niż dozwolona liczba klawiszy-2000-zwróci komunikat o błędzie, Param count too large .

Opublikuj szablon Zdalnej konfiguracji

Po pobraniu szablonu i poprawieniu go z żądanymi aktualizacjami możesz go opublikować. Opublikowanie szablonu zgodnie z opisem w tej sekcji powoduje zastąpienie całego istniejącego szablonu konfiguracji zaktualizowanym plikiem, a nowy aktywny szablon otrzymuje numer wersji o jeden większy niż szablon, który został zastąpiony.

Jeśli to konieczne, można użyć interfejsu API REST, aby cofnąć do poprzedniej wersji . W celu zmniejszenia ryzyka wystąpienia błędów w aktualizacji, można zweryfikować przed publikacją .

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);
      });
}

Jawa

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

Modyfikuj Zdalną konfigurację za pomocą REST API

Ta sekcja opisuje główne funkcje zdalnej konfiguracji REST API w https://firebaseremoteconfig.googleapis.com . Dla pełnej szczegółowości, zobacz odniesienia API .

Uzyskaj token dostępu do uwierzytelniania i autoryzacji żądań API

Projekty Firebase obsługują Google kont usług , których można użyć, aby zadzwonić API serwera Firebase z serwera aplikacji lub zaufanym środowisku. 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 upoważnić je do dostępu do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.

Aby wygenerować plik klucza prywatnego dla konta usługi:

  1. W konsoli Firebase, otwartych Ustawienia> Konta usług .

  2. Kliknij przycisk Utwórz nowy klucz prywatny, a następnie potwierdź klikając Generowanie klucza.

  3. Bezpiecznie przechowuj plik JSON zawierający klucz.

Podczas autoryzacji za pośrednictwem konta usługi masz dwie możliwości podania danych uwierzytelniających do swojej aplikacji. Można też ustawić GOOGLE_APPLICATION_CREDENTIALS zmienną środowiskową, czy można jednoznacznie przekazać ścieżkę do klucza konta usługi w kodzie. Pierwsza opcja jest bezpieczniejsza i zdecydowanie zalecana.

Aby ustawić zmienną środowiskową:

Ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS do ścieżki pliku pliku JSON, który zawiera 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 aplikacja Domyślne poświadczenia (ADC) aplikacji będzie w stanie domyślnie określić Twoje dane logowania, co pozwoli Ci używać danych logowania do konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.

Użyj poświadczeń Firebase wraz z Auth Biblioteki Google dla preferowanego języka aby pobrać krótkotrwałą OAuth 2.0 token dostępu:

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 internetowego JSON lub JWT. Aby uzyskać więcej informacji, zobacz JSON tokeny internetowych .

Pyton

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

Jawa

private 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 tokenu dostępu metoda odświeżania tokenu jest wywoływana automatycznie w celu pobrania zaktualizowanego tokenu dostępu.

Aby zezwolić na dostęp do zdalnego Config zwrócić zakres https://www.googleapis.com/auth/firebase.remoteconfig .

Zmodyfikuj szablon Zdalnej konfiguracji

Podczas pracy z szablonami Zdalnej konfiguracji należy pamiętać, że są one wersjonowane oraz że każda wersja ma ograniczony czas życia od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Zobacz Szablony i wersjonowania , aby uzyskać więcej informacji.

Pobierz aktualny szablon zdalnej konfiguracji

Możesz użyć interfejsów API zaplecza, aby pobrać bieżącą aktywną wersję szablonu Zdalnej konfiguracji w formacie JSON. Użyj następujących poleceń:

kędzior

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

To polecenie wyprowadza ładunek JSON do jednego pliku, a nagłówki (w tym Etag) do osobnego 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 API zwraca następujące JSON, wraz z oddzielnym nagłówku, który zawiera ETag , który służy do kolejnego wniosku.

Sprawdź poprawność szablonu Zdalnej konfiguracji

Opcjonalnie możesz sprawdzić poprawność aktualizacji przed ich opublikowaniem. Walidacji aktualizacje szablon dołączanie do publikowania życzenie parametr URL ?validate_only=true . W odpowiedzi kod statusu 200 i uaktualniony etag z przyrostkiem -0 oznacza, że aktualizacja została pomyślnie zweryfikowane. Każda odpowiedź inna niż 200 wskazuje, że dane JSON zawierają błędy, które należy poprawić przed opublikowaniem.

Zaktualizuj szablon Zdalnej konfiguracji

Po pobraniu szablonu i poprawieniu zawartości JSON z żądanymi aktualizacjami możesz go opublikować. Opublikowanie szablonu zgodnie z opisem w tej sekcji powoduje zastąpienie całego istniejącego szablonu konfiguracji zaktualizowanym plikiem, a nowy aktywny szablon otrzymuje numer wersji o jeden większy niż szablon, który został zastąpiony.

Jeśli to konieczne, można użyć interfejsu API REST, aby cofnąć do poprzedniej wersji . W celu zmniejszenia ryzyka wystąpienia błędów w aktualizacji, można zweryfikować przed publikacją .

kędzior

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

Z tego curl poleceniu można określić zawartości przy użyciu znaku „@”, a następnie nazwę 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 żądania zapisu The ETag jest modyfikowana przez tego polecenia oraz zaktualizowany ETag jest w nagłówkach odpowiedzi następnego PUT polecenia.

Zmodyfikuj warunki zdalnej konfiguracji

Możesz programowo modyfikować warunki i wartości warunkowe Zdalnej konfiguracji. Korzystając z interfejsu API REST, musisz edytować szablon bezpośrednio, aby zmodyfikować warunki 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."
    }
  }
}

Modyfikacje wyżej najpierw określić zestaw warunków, a następnie określa wartości domyślnych oraz parametr stanu, na podstawie wartości (warunkowych) wartości dla każdego parametru. Dodaje również opcjonalny opis dla każdego elementu; podobnie jak komentarze do kodu, są one przeznaczone dla programistów i nie są wyświetlane w aplikacji. ETag jest również do celów kontroli wersji.

Interfejsy API zaplecza Zdalnej konfiguracji udostępniają kilka warunków i operatorów porównania, których można użyć do zmiany zachowania i wyglądu aplikacji. Aby dowiedzieć się więcej na temat warunków i operatorów obsługiwanych dla tych warunków, zobacz warunkową odniesienie ekspresji .

Kody błędów HTTP

Kod statusu Oznaczający
200 Pomyślnie zaktualizowano
400 Wystąpił błąd sprawdzania poprawności. Na przykład, wniosek zawierający więcej niż dozwolona liczba klawiszy-2000-zwróciłby 400 (Bad Request) z komunikatem o błędzie, Param count too large . Ponadto ten kod stanu HTTPS może wystąpić w tych dwóch sytuacjach:
  • Wystąpił błąd niezgodności wersji, ponieważ zestaw wartości i warunków został zaktualizowany od czasu ostatniego pobrania wartości ETag. Aby rozwiązać ten problem, należy użyć GET polecenie, aby uzyskać świeży szablon i wartości ETag zaktualizować szablon, a następnie przesłać za pomocą tego szablonu i świeże wartości ETag.
  • PUT polecenia (Aktualizuj zdalne żądanie szablon Config) powstał bez określania If-Match nagłówek.
401 Wystąpił błąd autoryzacji (nie podano tokena dostępu lub interfejs Firebase Remote Config REST API nie został dodany do Twojego projektu w Cloud Developer Console)
403 Wystąpił błąd uwierzytelniania (podano nieprawidłowy token dostępu)
500 Wystąpił błąd wewnętrzny. W przypadku tego błędu, złożyć zgłoszenie do pomocy technicznej Firebase

Kod stanu 200 oznacza, że ​​szablon Zdalnej konfiguracji (parametry, wartości i warunki projektu) został zaktualizowany i jest teraz dostępny dla aplikacji korzystających z tego projektu. Inne kody stanu wskazują, że istniejący wcześniej szablon Zdalnej konfiguracji nadal obowiązuje.

Po przesłaniu aktualizacji szablonu przejdź do konsoli Firebase, aby sprawdzić, czy zmiany pojawiają się zgodnie z oczekiwaniami. Jest to niezwykle ważne, ponieważ kolejność warunków wpływa na to jak są one oceniane (pierwszy stan, który ocenia true staje się skuteczne).

Wykorzystanie ETagów i wymuszone aktualizacje

Interfejs API REST Remote Config używa tagu encji (ETag), aby zapobiec wyścigom i nakładającym się aktualizacjom zasobów. Aby dowiedzieć się więcej o Etags patrz ETag - HTTP .

Dla REST API, Google zaleca, aby buforować ETag dostarczane przez najnowsze GET polecenia, a następnie użyć tej wartości ETag w If-Match nagłówka żądania przy wydawaniu PUT polecenia. Jeśli twoje PUT wyniki dowodzenia w HTTPS Kod statusu 409, należy wydać nową GET polecenie zdobycia nowego ETag i szablon do wykorzystania przy następnej PUT polecenia.

Można obejść ETAG, a także ochronę przed to, że zapewnia, zmuszając pilota zdalnego szablon Config być aktualizowane w następujący sposób: If-Match: * Jednak takie podejście nie jest zalecane, ponieważ grozi to powoduje utratę aktualizacje do Remote Config szablon, jeśli wielu klientów aktualizuje szablon Zdalnej konfiguracji. Ten rodzaj konfliktu 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.

W celu uzyskania wskazówek na temat zarządzania zdalnego wersje szablonów Config, patrz Zdalna szablony konfiguracyjne i wersjonowania .