Automatycznie modyfikuj Zdalną konfigurację

Z tego dokumentu dowiesz się, jak programowo odczytywać i modyfikować zestaw parametrów i warunków w formacie JSON, znany jako Remote Config szablon. Dzięki temu możesz wprowadzać zmiany w szablonie na backendzie, które aplikacja kliencka może pobrać za pomocą biblioteki klienta.

Korzystając z interfejsu Remote Config REST API lub pakietów Admin SDKs opisanych w tym przewodniku, możesz pominąć zarządzanie szablonem w konsoli Firebase i bezpośrednio zintegrować Remote Config zmiany z własnymi procesami. Na przykład za pomocą Remote Config interfejsów API backendu możesz:

• Planować Remote Config aktualizacje. Używając wywołań interfejsu API w połączeniu z zadaniem cron, możesz regularnie zmieniać wartości Remote Config.
• Importować zbiorczo wartości konfiguracji , aby sprawnie przejść z własnego systemu na Firebase Remote Config.

• Używać 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 następnie automatycznie wyłączyć tę promocję, gdy wykryjesz, że wystarczająca liczba osób skorzystała z nowej funkcji.

  

W sekcjach tego przewodnika opisujemy operacje, które możesz wykonywać za pomocą interfejsów API backendu Remote Config. Aby przejrzeć kod, który wykonuje te zadania za pomocą interfejsu REST API, zapoznaj się z jedną z tych przykładowych aplikacji:

• Szybkie wprowadzenie do interfejsu API (typu) REST zdalnej konfiguracji Firebase w języku Java
• Szybkie wprowadzenie do interfejsu Zdalna konfiguracja Firebase REST API w języku Node.js
• Szybki start z interfejsem Zdalna konfiguracja Firebase REST API w języku Python

Modyfikowanie Zdalnej konfiguracji za pomocą pakietu Firebase Admin SDK

Pakiet Admin SDK to zestaw bibliotek serwerowych, które umożliwiają interakcję z Firebase w środowiskach z uprawnieniami. Oprócz aktualizowania do Remote Config, Admin SDK umożliwia generowanie i weryfikowanie tokenów uwierzytelniania Firebase, odczytywanie i zapisywanie danych w Realtime Database, itp. Więcej informacji o wymaganiach wstępnych i konfiguracji Admin SDK znajdziesz w artykule Dodawanie pakietu Firebase Admin SDK do serwera.

W typowym Remote Config procesie możesz pobrać bieżący szablon, zmodyfikować niektóre parametry lub grupy parametrów i warunki, zweryfikować szablon, a następnie go opublikować. Zanim wywołasz te interfejsy API, musisz autoryzować żądania z pakietu SDK.

Inicjowanie pakietu SDK i autoryzowanie żądań do interfejsu API

Gdy zainicjujesz Admin SDK bez parametrów, pakiet SDK użyje domyślnego uwierzytelniania aplikacji Google i odczyta opcje ze zmiennej środowiskowej FIREBASE_CONFIG. Jeśli zawartość zmiennej FIREBASE_CONFIG zaczyna się od {, zostanie ona przeanalizowana jako obiekt JSON. W przeciwnym razie pakiet SDK przyjmie, że ciąg znaków jest nazwą pliku JSON zawierającego opcje.

Przykład:

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

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 każda wersja ma ograniczony czas życia – od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Więcej informacji znajdziesz w artykule Szablony i wersjonowanie.

Za pomocą interfejsów API backendu możesz pobrać bieżącą aktywną wersję szablonu Remote Config w formacie JSON.

Parametry i wartości parametrów utworzone specjalnie jako warianty w eksperymencie A/B Testing nie są uwzględniane w eksportowanych szablonach.

Aby pobrać szablon:

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

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ć Remote Config parametry 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:

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

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.

Modyfikowanie warunków Zdalnej konfiguracji

Możesz programowo modyfikować i dodawać Remote Config warunki oraz wartości warunkowe. Aby na przykład dodać nowy warunek:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

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żyć 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:

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

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 duplikaty kluczy parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki oraz 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.

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 nowy aktywny szablon otrzyma numer wersji o 1 większy od numeru szablonu, który zastąpił.

W razie potrzeby możesz użyć interfejsu REST API, aby wycofać zmiany do poprzedniej wersji. Aby zmniejszyć ryzyko wystąpienia błędów w aktualizacji, możesz zweryfikować szablon przed opublikowaniem.

Remote Config personalizacje i warunki są uwzględniane w pobranych szablonach, dlatego podczas publikowania w innym projekcie musisz pamiętać o tych ograniczeniach:

• Personalizacji nie można importować z projektu do projektu.

  Jeśli na przykład masz włączone personalizacje w projekcie, a następnie pobierzesz i edytujesz szablon, możesz go opublikować w tym samym projekcie, ale nie możesz go opublikować w innym projekcie, dopóki nie usuniesz z niego personalizacji.

• Warunki można importować z projektu do projektu, ale pamiętaj, że przed opublikowaniem w projekcie docelowym powinny istnieć wszystkie konkretne wartości warunkowe (takie jak identyfikatory aplikacji lub odbiorcy).

  Jeśli na przykład 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 on warunek, który opiera się na konkretnym identyfikatorze aplikacji lub odbiorcach, którzy nie istnieją w projekcie docelowym, weryfikacja zakończy się niepowodzeniem.

• Jeśli szablon, który chcesz opublikować, zawiera warunki oparte na Google Analytics, Analytics musi być włączona w projekcie docelowym.

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

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 REST API

W tej sekcji opisujemy główne możliwości interfejsu Remote Config REST API pod adresem https://firebaseremoteconfig.googleapis.com. Szczegółowe informacje znajdziesz w dokumentacji 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.

Wszystkie konta usługi w projekcie w Firebase możesz wyświetlić w settings ustawieniach > Konta usługi na karcie.

Aby uwierzytelnić konto usługi i autoryzować je do uzyskiwania 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 otwórz ustawienia na karcie settings Ustawienia > Konta usługi.

2. Kliknij Wygeneruj nowy klucz prywatny, a następnie potwierdź, klikając Wygeneruj klucz.

3. 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 wyraźnie 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 dotyczy tylko bieżącej sesji powłoki, więc jeśli otworzysz nową sesję, ustaw ją ponownie.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Po wykonaniu powyższych czynności domyślne uwierzytelnianie aplikacji (ADC) będzie mogło niejawnie określić 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 razem z biblioteką Google Auth Library w preferowanym języku, aby pobrać krótkotrwały token dostępu OAuth 2.0:

 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);
      });
}
index.js

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
configure.py

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

Gdy token dostępu wygaśnie, automatycznie zostanie wywołana metoda odświeżania tokena, 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 każda wersja ma ograniczony czas życia – od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Więcej informacji znajdziesz w artykule Szablony i wersjonowanie.

Pobieranie bieżącego szablonu Zdalnej konfiguracji

Za pomocą interfejsów API backendu możesz pobrać bieżącą aktywną wersję szablonu Remote Config w formacie JSON.

Parametry i wartości parametrów utworzone specjalnie jako warianty w eksperymencie A/B Testing nie są uwzględniane w eksportowanych szablonach.

Użyj tych poleceń:

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

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

Weryfikowanie szablonu Zdalnej konfiguracji

Opcjonalnie możesz zweryfikować zmiany przed ich opublikowaniem. Aby zweryfikować aktualizacje szablonu, dołącz do żądania publikacji parametr 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 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 nowy aktywny szablon otrzyma numer wersji o 1 większy od numeru szablonu, który zastąpił.

W razie potrzeby możesz użyć interfejsu REST API, aby wycofać zmiany do poprzedniej wersji. Aby zmniejszyć ryzyko wystąpienia błędów w aktualizacji, możesz zweryfikować szablon przed opublikowaniem.

Remote Config personalizacje i warunki są uwzględniane w pobranych szablonach, dlatego podczas publikowania w innym projekcie musisz pamiętać o tych ograniczeniach:

• Personalizacji nie można importować z projektu do projektu.

  Jeśli na przykład masz włączone personalizacje w projekcie, a następnie pobierzesz i edytujesz szablon, możesz go opublikować w tym samym projekcie, ale nie możesz go opublikować w innym projekcie, dopóki nie usuniesz z niego personalizacji.

• Warunki można importować z projektu do projektu, ale pamiętaj, że przed opublikowaniem w projekcie docelowym powinny istnieć wszystkie konkretne wartości warunkowe (takie jak identyfikatory aplikacji lub odbiorcy).

  Jeśli na przykład 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 on warunek, który opiera się na konkretnym identyfikatorze aplikacji lub odbiorcach, którzy nie istnieją w projekcie docelowym, weryfikacja zakończy się niepowodzeniem.

• Jeśli szablon, który chcesz opublikować, zawiera warunki oparte na Google Analytics, Analytics musi być włączona w projekcie docelowym.

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

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

Modyfikowanie warunków Zdalnej konfiguracji

Możesz programowo modyfikować Remote Config warunki oraz wartości warunkowe. Aby zmodyfikować warunki za pomocą interfejsu REST API, musisz edytować szablon bezpośrednio 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. Dodają też opcjonalny opis każdego elementu. Podobnie jak komentarze w kodzie, są one przeznaczone dla programistów i nie są wyświetlane w aplikacji. Podawany jest też tag ETag na potrzeby kontroli wersji.

Interfejsy API backendu Remote Config udostępniają kilka warunków i operatorów porównania , których możesz użyć 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 200 oznacza, że szablon Remote Config (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 nadal obowiązuje poprzedni Remote Config szablon.

Po przesłaniu aktualizacji szablonu sprawdź w konsoli Firebase, czy zmiany są widoczne zgodnie z oczekiwaniami. Jest to bardzo ważne, ponieważ kolejność warunków wpływa na sposób ich oceniania (obowiązuje pierwszy warunek, który przyjmuje wartość true).

Użycie tagu ETag i wymuszone aktualizacje

Interfejs Remote Config REST API używa tagu encji (ETag), aby zapobiegać wyścigom 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 buforowanie tagu ETag podanego przez najnowsze polecenie GET i używanie tej wartości tagu ETag w nagłówku żądania If-Match podczas wydawania poleceń PUT. Jeśli polecenie PUT spowoduje zwrócenie kodu stanu HTTPS 409, wydaj nowe polecenie GET, aby uzyskać nowy tag ETag i szablon do użycia w następnym poleceniu 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ż może ono spowodować utratę aktualizacji szablonu Remote Config, jeśli wielu klientów aktualizuje ten szablon 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 Firebase użytkowników konsoli.

Wskazówki dotyczące zarządzania wersjami szablonów Remote Config znajdziesz w artykule Szablony i obsługa wersji Zdalnej konfiguracji.