Google is committed to advancing racial equity for Black communities. See how.
Ta strona została przetłumaczona przez Cloud Translation API.
Switch to English

Zmodyfikuj zdalną konfigurację programowo

W tym dokumencie opisano, jak programowo odczytać i zmodyfikować zestaw parametrów i warunków w formacie JSON, znanych jako szablon zdalnej konfiguracji. Umożliwia to wprowadzanie zmian w szablonach w zapleczu, które aplikacja kliencka może pobrać przy użyciu biblioteki klienta.

Korzystając z interfejsu Remote Config REST API lub zestawów Admin SDK opisanych w tym przewodniku, możesz ominąć zarządzanie szablonem w konsoli Firebase, aby bezpośrednio zintegrować zmiany Remote Config z własnymi procesami. Na przykład w przypadku interfejsów API zaplecza Remote Config można:

  • Planowanie aktualizacji Remote Config . Używając wywołań API w połączeniu z zadaniem cron, możesz zmieniać wartości Remote Config w regularnych odstępach czasu.
  • Zbiorcze importowanie wartości konfiguracyjnych w celu efektywnego przejścia z własnego zastrzeżonego systemu do zdalnej konfiguracji Firebase.
  • Użyj Remote Config z Cloud Functions for Firebase , zmieniając wartości w swojej aplikacji na podstawie zdarzeń, które mają miejsce po stronie serwera. Na przykład możesz użyć Zdalnej konfiguracji do promowania nowej funkcji w swojej aplikacji, a następnie automatycznie wyłączyć tę promocję po wykryciu, że wystarczająca liczba osób weszła w interakcję z nową funkcją.

W kolejnych 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:

Zmodyfikuj zdalną konfigurację przy użyciu pakietu Firebase Admin SDK

Admin SDK to zestaw bibliotek serwera, które umożliwiają interakcję z Firebase w uprzywilejowanych środowiskach. Oprócz wykonywania aktualizacji zdalnej konfiguracji, pakiet Admin SDK umożliwia generowanie i weryfikację tokenów uwierzytelniania Firebase, odczytywanie i zapisywanie w bazie 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żna pobrać bieżący szablon, zmodyfikować niektóre parametry lub grupy parametrów i warunki, sprawdzić poprawność szablonu, a następnie opublikować go. Przed wykonaniem tych wywołań interfejsu API należy autoryzować żądania z zestawu SDK.

Zainicjuj zestaw SDK i autoryzuj żądania interfejsu API

Po zainicjowaniu pakietu Admin SDK bez parametrów 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 SDK zakłada, że ​​ciąg jest nazwą pliku JSON zawierającego opcje.

Na przykład:

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

Pobierz aktualny szablon zdalnej konfiguracji

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

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

Zmodyfikuj parametry Zdalnej konfiguracji

Można 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żna dodać parametr sterujący wyświetlaniem informacji sezonowych:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: '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 należy jawnie opublikować szablon po wprowadzeniu zmian.

Zmodyfikuj warunki Zdalnej konfiguracji

Możesz programowo modyfikować i dodawać warunki i wartości warunkowe Remote Config. 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',
  });
}

We wszystkich przypadkach należy jawnie opublikować szablon po wprowadzeniu zmian.

Interfejsy API zaplecza 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 w tych warunkach, zobacz informacje o wyrażeniach warunkowych .

Sprawdź poprawność szablonu zdalnej konfiguracji

Opcjonalnie możesz zweryfikować swoje aktualizacje przed ich opublikowaniem, 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);
      });
}

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 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 przy użyciu żą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 zostanie przypisany numer wersji o jeden większy niż szablon, który zastąpił.

W razie potrzeby możesz użyć interfejsu API REST, aby przywrócić poprzednią wersję . Aby zminimalizować ryzyko wystąpienia błędów w aktualizacji, możesz zweryfikować ją przed opublikowaniem .

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

Zmodyfikuj zdalną konfigurację za pomocą interfejsu API REST

W tej sekcji opisano główne możliwości interfejsu Remote Config REST API pod https://firebaseremoteconfig.googleapis.com . Aby uzyskać szczegółowe informacje, zobacz dokumentację interfejsu 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 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:

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

  2. Kliknij opcję Generuj nowy klucz prywatny , a następnie potwierdź, klikając opcję 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ń do 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 jest zdecydowanie zalecana.

Aby ustawić zmienną środowiskową:

Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę do pliku JSON, który zawiera klucz Twojego konta usługi. Ta zmienna ma zastosowanie tylko do 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"

Windows

Z PowerShell:

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

Po wykonaniu powyższych kroków domyślne poświadczenia aplikacji (ADC) są w stanie niejawnie określić Twoje poświadczenia, umożliwiając korzystanie z poświadczeń konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.

Użyj swoich danych logowania Firebase wraz z biblioteką klienta interfejsu API Google dla preferowanego języka, aby pobrać krótkotrwały token dostępu OAuth 2.0:

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 Google API uwierzytelnia żądanie za pomocą tokena internetowego JSON lub JWT. Aby uzyskać więcej informacji, zobacz tokeny internetowe JSON .

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 {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

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 jej utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, z łącznym limitem 300 przechowywanych wersji. Aby uzyskać więcej informacji, zobacz Szablony i przechowywanie wersji .

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 oddzielnego 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 interfejsu API zwraca następujący kod JSON wraz z oddzielnym nagłówkiem zawierającym element ETag używany do kolejnego żądania.

Sprawdź poprawność szablonu zdalnej konfiguracji

Opcjonalnie możesz zweryfikować swoje aktualizacje przed ich opublikowaniem. Sprawdź ?validate_only=true aktualizacji szablonów, dołączając do żądania publikacji parametr adresu URL ?validate_only=true Validate_only ?validate_only=true . W odpowiedzi kod statusu 200 i zaktualizowany etag z przyrostkiem -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 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 nowemu aktywnemu szablonowi zostanie przypisany numer wersji o jeden większy niż szablon, który zastąpił.

W razie potrzeby możesz użyć interfejsu API REST, aby przywrócić poprzednią wersję . Aby ograniczyć ryzyko wystąpienia błędów w aktualizacji, możesz zweryfikować ją przed opublikowaniem .

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

W przypadku tego polecenia curl można określić zawartość, używając znaku „@”, po którym następuje nazwa 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 żądanie zapisu, ETag jest modyfikowany przez to polecenie, a zaktualizowany ETag jest dostarczany w nagłówkach odpowiedzi następnego polecenia PUT .

Zmodyfikuj warunki Zdalnej konfiguracji

Można 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 przez programistów i nie są wyświetlane w aplikacji. Dostarczono również ETag do celów kontroli wersji.

Interfejsy API zaplecza 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 w tych warunkach, zobacz informacje o wyrażeniach warunkowych .

Kody błędów HTTP

Kod statusu Znaczenie
200 Zaktualizowano pomyślnie
400 Wystąpił błąd weryfikacji. Na przykład żądanie zawierające więcej niż dozwoloną liczbę kluczy - 2000 - zwróci 400 (Złe żądanie) z komunikatem o błędzie „ Param count too large . Ten kod stanu HTTPS może również wystąpić w następujących 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ć polecenia GET aby uzyskać nowy szablon i wartość ETag, zaktualizować szablon, a następnie przesłać przy użyciu tego szablonu i nowej wartości ETag.
  • Wykonano polecenie PUT (żądanie aktualizacji szablonu zdalnej konfiguracji) bez określania nagłówka If-Match .
401 Wystąpił błąd autoryzacji (nie podano tokena dostępu lub interfejs REST API Firebase Remote Config 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. Jeśli wystąpi ten błąd, prześlij zgłoszenie do pomocy Firebase

Kod stanu równy 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 szablon zdalnej konfiguracji, który istniał wcześniej, nadal obowiązuje.

Po przesłaniu aktualizacji szablonu przejdź do konsoli Firebase, aby sprawdzić, czy zmiany są zgodne z oczekiwaniami. Jest to krytyczne, ponieważ kolejność warunków wpływa na sposób ich oceny (pierwszy warunek, który ocenia wartość true zaczyna obowiązywać).

Użycie ETag i wymuszone aktualizacje

Interfejs API REST Remote Config używa znacznika encji (ETag), aby zapobiec sytuacjom wyścigu i nakładającym się aktualizacjom zasobów. Aby dowiedzieć się więcej o ETagach, 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 skutkuje kodem stanu HTTPS 409, należy wydać nowe polecenie GET aby uzyskać nowy ETag i szablon do użycia z następnym poleceniem PUT .

Możesz obejść ETag i ochronę, którą zapewnia, wymuszając aktualizację szablonu Remote Config w następujący sposób: If-Match: * Jednak to podejście nie jest zalecane, ponieważ grozi utratą aktualizacji do Remote Config template, jeśli wielu klientów aktualizuje szablon Remote Config. Ten rodzaj konfliktu może wystąpić w przypadku wielu klientów korzystających z interfejsu API lub sprzecznych aktualizacji od klientów API i użytkowników konsoli Firebase.

Aby uzyskać wskazówki dotyczące zarządzania wersjami szablonów Remote Config, zobacz szablony Remote Config i przechowywanie wersji .