Programowa modyfikacja Zdalnej konfiguracji

W tym dokumencie opisano, w jaki sposób można programowo odczytywać i modyfikować zestaw parametrów i warunków w formacie JSON, znany jako szablon zdalnej konfiguracji . Dzięki temu można wprowadzać zmiany szablonów w zapleczu, które aplikacja kliencka może pobrać przy użyciu biblioteki klienckiej.

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

• Planowanie aktualizacji Zdalnej konfiguracji . Używając wywołań API w połączeniu z zadaniem cron, możesz regularnie zmieniać wartości Zdalnej konfiguracji.
• Importuj wsadowo wartości konfiguracyjne , aby skutecznie przejść z własnego zastrzeżonego systemu do Firebase Remote Config.

• Użyj zdalnej konfiguracji z Cloud Functions dla Firebase , zmieniając wartości w swojej aplikacji na podstawie zdarzeń zachodzących 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ę, gdy wykryjesz, że wystarczająca liczba osób weszła w interakcję z nową funkcją.

  

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

• Firebase Remote Config REST API Java Szybki start
• Firebase Remote Config REST API Node.js Szybki start
• Firebase Remote Config REST API Python Szybki start

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

Pakiet Admin SDK to zestaw bibliotek serwera, które umożliwiają interakcję z Firebase z uprzywilejowanych środowisk. Oprócz wykonywania aktualizacji Remote Config pakiet Admin SDK umożliwia generowanie i weryfikację tokenów uwierzytelniania Firebase, odczytywanie i zapisywanie danych z bazy danych czasu rzeczywistego itd. Aby dowiedzieć się więcej o wymaganiach wstępnych i konfiguracji pakietu Admin SDK, zobacz Dodawanie pakietu Firebase Admin SDK do serwera .

W typowym przepływie zdalnej konfiguracji możesz pobrać bieżący szablon, zmodyfikować niektóre parametry lub grupy parametrów i warunki, zweryfikować szablon, a następnie go opublikować. Przed wykonaniem tych wywołań interfejsu API musisz autoryzować żądania z zestawu SDK.

Zainicjuj zestaw SDK i autoryzuj żądania interfejsu API

Gdy zainicjujesz pakiet Admin SDK bez parametrów, pakiet SDK używa domyślnych danych logowania aplikacji Google i odczytuje opcje ze zmiennej środowiskowej FIREBASE_CONFIG . Jeśli zawartość zmiennej FIREBASE_CONFIG zaczyna się od { , zostanie przeanalizowana jako obiekt JSON. W przeciwnym razie zestaw SDK zakłada, że ​​ciąg jest nazwą pliku JSON zawierającego opcje.

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

Pobierz bieżący szablon zdalnej konfiguracji

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

Możesz użyć interfejsów API zaplecza, aby uzyskać bieżącą aktywną wersję szablonu Zdalnej konfiguracji w formacie JSON.

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

Aby otrzymać 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());

Zmodyfikuj parametry Zdalnej konfiguracji

Możesz programowo modyfikować i dodawać parametry i grupy parametrów Remote Config. Na przykład do istniejącej grupy parametrów o nazwie „nowe_menu” możesz dodać parametr kontrolujący 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 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:

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

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

Interfejsy API zaplecza usługi Remote Config 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 o warunkach i operatorach obsługiwanych przez te warunki, zobacz informacje o wyrażeniach warunkowych .

Sprawdź poprawność szablonu Zdalnej konfiguracji

Opcjonalnie możesz zweryfikować swoje aktualizacje przed ich opublikowaniem, tak jak pokazano:

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 sprawdzania poprawności sprawdza błędy, takie jak zduplikowane klucze dla parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki lub źle sformatowane etags. 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 poprawieniu go za pomocą żądanych aktualizacji można go opublikować. Opublikowanie szablonu zgodnie z opisem w tej sekcji powoduje zastąpienie całego istniejącego szablonu konfiguracji zaktualizowanym plikiem, a nowemu aktywnemu szablonowi zostaje przypisany numer wersji o jeden większy niż szablon, który zastąpił.

W razie potrzeby możesz użyć REST API, aby przywrócić poprzednią wersję . Aby ograniczyć ryzyko błędów w aktualizacji, możesz sprawdzić poprawność przed opublikowaniem .

Personalizacja i warunki usługi Remote Config są zawarte w pobranych szablonach, dlatego podczas próby opublikowania w innym projekcie należy pamiętać o następujących ograniczeniach:

• Personalizacja nie może być importowana z projektu do projektu.

  Na przykład, jeśli masz włączone personalizacje w swoim projekcie oraz pobierzesz i edytujesz szablon, możesz opublikować go w tym samym projekcie, ale nie możesz go opublikować w innym projekcie, chyba że usuniesz personalizacje z szablonu.

• Warunki można importować z projektu do projektu, ale należy pamiętać, że wszelkie określone wartości warunkowe (takie jak identyfikatory aplikacji lub odbiorcy) powinny istnieć w projekcie docelowym przed opublikowaniem.

  Na przykład, jeśli masz parametr Remote Config, który używa warunku, który określa wartość platformy iOS , szablon można opublikować w innym projekcie, ponieważ wartości platformy są takie same dla każdego projektu. Jeśli jednak zawiera warunek, który opiera się na określonym identyfikatorze aplikacji lub grupie odbiorców, która nie istnieje w projekcie docelowym, weryfikacja zakończy się niepowodzeniem.

• Jeśli szablon, który planujesz opublikować, zawiera warunki, które opierają się na Google Analytics, Analytics musi być włączony w docelowym projekcie.

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

Zmodyfikuj Zdalną konfigurację za pomocą interfejsu API REST

W tej sekcji opisano główne możliwości interfejsu API REST usługi Remote Config pod https://firebaseremoteconfig.googleapis.com . Aby uzyskać szczegółowe informacje, zobacz informacje o interfejsie API .

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

Projekty Firebase obsługują konta usług 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ć poświadczeń uzyskanych za pośrednictwem tego konta usługi, aby autoryzować żądania serwera.

Aby uwierzytelnić konto usługi i autoryzować dostęp do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.

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

1. W konsoli Firebase otwórz Ustawienia > Konta usług .

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

3. Bezpiecznie przechowuj plik JSON zawierający klucz.

W przypadku autoryzacji za pośrednictwem konta usługi masz dwie możliwości podania poświadczeń 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ę do 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 tę zmienną 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 kroków domyślne dane logowania aplikacji (ADC) mogą niejawnie określić Twoje dane logowania, umożliwiając korzystanie z danych logowania do konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.

Użyj poświadczeń Firebase razem z Biblioteką Google Auth dla preferowanego języka, 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

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

Po wygaśnięciu tokenu dostępu metoda odświeżania tokenu jest wywoływana automatycznie w celu pobrania zaktualizowanego tokenu dostępu.

Aby autoryzować dostęp do Zdalnej konfiguracji, poproś o 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 i że każda wersja ma ograniczony czas życia od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, z łącznym limitem 300 przechowywanych wersji. Zobacz Szablony i przechowywanie wersji, aby uzyskać więcej informacji.

Pobierz bieżący szablon zdalnej konfiguracji

Możesz użyć interfejsów API zaplecza, aby uzyskać bieżącą aktywną wersję szablonu Zdalnej konfiguracji w formacie JSON.

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

Użyj następujących 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

Sprawdź poprawność szablonu Zdalnej konfiguracji

Opcjonalnie możesz zweryfikować swoje aktualizacje przed ich opublikowaniem. Sprawdź poprawność aktualizacji szablonu, dołączając do żądania publikacji parametr adresu URL ?validate_only=true . W odpowiedzi kod stanu 200 i zaktualizowany etag z sufiksem -0 oznaczają, że aktualizacja została pomyślnie zweryfikowana. 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 treści JSON za pomocą żądanych aktualizacji możesz go opublikować. Opublikowanie szablonu zgodnie z opisem w tej sekcji powoduje zastąpienie całego istniejącego szablonu konfiguracji zaktualizowanym plikiem, a nowemu aktywnemu szablonowi zostaje przypisany numer wersji o jeden większy niż szablon, który zastąpił.

W razie potrzeby możesz użyć REST API, aby przywrócić poprzednią wersję . Aby ograniczyć ryzyko błędów w aktualizacji, możesz sprawdzić poprawność przed opublikowaniem .

Personalizacja i warunki usługi Remote Config są zawarte w pobranych szablonach, dlatego podczas próby opublikowania w innym projekcie należy pamiętać o następujących ograniczeniach:

• Personalizacja nie może być importowana z projektu do projektu.

  Na przykład, jeśli masz włączone personalizacje w swoim projekcie oraz pobierzesz i edytujesz szablon, możesz opublikować go w tym samym projekcie, ale nie możesz go opublikować w innym projekcie, chyba że usuniesz personalizacje z szablonu.

• Warunki można importować z projektu do projektu, ale należy pamiętać, że wszelkie określone wartości warunkowe (takie jak identyfikatory aplikacji lub odbiorcy) powinny istnieć w projekcie docelowym przed opublikowaniem.

  Na przykład, jeśli masz parametr Remote Config, który używa warunku, który określa wartość platformy iOS , szablon można opublikować w innym projekcie, ponieważ wartości platformy są takie same dla każdego projektu. Jeśli jednak zawiera warunek, który opiera się na określonym identyfikatorze aplikacji lub grupie odbiorców, która nie istnieje w projekcie docelowym, weryfikacja zakończy się niepowodzeniem.

• Jeśli szablon, który planujesz opublikować, zawiera warunki, które opierają się na Google Analytics, Analytics musi być włączony w docelowym projekcie.

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

Zmodyfikuj warunki Zdalnej konfiguracji

Możesz programowo modyfikować warunki i wartości warunkowe Zdalnej konfiguracji. W przypadku interfejsu API REST należy bezpośrednio edytować szablon, 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."
    }
  }
}

Powyższe modyfikacje najpierw definiują zestaw warunków, a następnie definiują wartości domyślne i wartości parametrów warunkowych ( wartości warunkowe ) dla każdego parametru. Dodaje również opcjonalny opis dla każdego elementu; podobnie jak komentarze do kodu, są one przeznaczone do użytku programistów i nie są wyświetlane w aplikacji. Do celów kontroli wersji udostępniany jest również znacznik ETag .

Interfejsy API zaplecza usługi Remote Config 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 o warunkach i operatorach obsługiwanych przez te warunki, zobacz informacje o wyrażeniach warunkowych .

Kody błędów HTTP

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

Po przesłaniu aktualizacji szablonu przejdź do konsoli Firebase, aby sprawdzić, czy zmiany pojawiają się zgodnie z oczekiwaniami. Ma to krytyczne znaczenie, ponieważ kolejność warunków wpływa na sposób ich oceny (działa pierwszy warunek, który ocenia wartość true ).

Użycie ETag i wymuszone aktualizacje

Interfejs API REST usługi Remote Config używa tagu encji (ETag), aby zapobiec sytuacji wyścigu i nakładającym się aktualizacjom zasobów. Aby dowiedzieć się więcej o tagach ETag, zobacz ETag — HTTP .

W przypadku interfejsu API REST Google zaleca buforowanie ETag dostarczonego przez najnowsze polecenie GET i używanie tej wartości ETag w nagłówku żądania If-Match podczas wydawania poleceń PUT . Jeśli polecenie PUT spowoduje wyświetlenie kodu stanu HTTPS 409, należy wydać nowe polecenie GET , aby uzyskać nowy znacznik ETag i szablon do użycia z następnym poleceniem PUT .

Możesz obejść ETag i zapewnianą przez niego ochronę, wymuszając aktualizację szablonu Zdalnej konfiguracji w następujący sposób: If-Match: * Jednak to podejście nie jest zalecane, ponieważ grozi utratą aktualizacji Zdalnej konfiguracji 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.

Aby uzyskać wskazówki dotyczące zarządzania wersjami szablonów zdalnej konfiguracji, zobacz temat Szablony zdalnej konfiguracji i przechowywanie wersji .