Mẫu cấu hình và phiên bản từ xa

Mẫu Cấu hình từ xa là tập hợp các tham số và điều kiện có định dạng JSON phía máy chủ mà bạn đã tạo cho dự án Firebase của mình. Bạn có thể sửa đổi và quản lý mẫu bằng bảng điều khiển Firebase, bảng điều khiển này hiển thị nội dung của mẫu ở định dạng đồ họa trong tab Tham sốĐiều kiện . Bạn cũng có thể sử dụng API REST cấu hình từ xa và SDK quản trị hoặc CLI Firebase để sửa đổi và quản lý cấu hình của mình.

Đây là một ví dụ về tệp mẫu:

  {
    "conditions": [
      {
        "name": "ios",
        "expression": "device.os == 'ios'"
      }
    ],
    "parameters": {
      "welcome_message": {
        "defaultValue": {
          "value": "Welcome to this sample app"
        },
        "conditionalValues": {
          "ios": {
            "value": "Welcome to this sample iOS app"
          }
        }
      },
      "welcome_message_caps": {
        "defaultValue": {
          "value": "false"
        }
      },
      "header_text": {
        "defaultValue": {
          "useInAppDefault": true
        }
      }
    },
    "version": {
      "versionNumber": "28",
      "updateTime": "2020-05-14T18:39:38.994Z",
      "updateUser": {
        "email": "user@google.com"
      },
      "updateOrigin": "CONSOLE",
      "updateType": "INCREMENTAL_UPDATE"
    }
  }

Mỗi lần bạn cập nhật các tham số, Remote Config sẽ tạo một mẫu Remote Config phiên bản mới và lưu trữ mẫu trước đó dưới dạng phiên bản mà bạn có thể truy xuất hoặc quay lại khi cần. Số phiên bản được tăng tuần tự từ giá trị ban đầu được lưu trữ bởi Cấu hình từ xa. Tất cả các mẫu đều bao gồm trường version như được hiển thị, chứa siêu dữ liệu về phiên bản cụ thể đó.

Với bảng điều khiển Firebase, Firebase CLI hoặc API phụ trợ Cấu hình từ xa, bạn có thể thực hiện các tác vụ quản lý phiên bản sau:

  • Liệt kê tất cả các phiên bản mẫu được lưu trữ
  • Truy xuất một phiên bản cụ thể
  • Quay lại một phiên bản cụ thể

Bạn có thể xóa các mẫu Cấu hình từ xa nếu cần từ trang Lịch sử thay đổi trên bảng điều khiển Cấu hình từ xa. Có tổng giới hạn là 300 phiên bản được lưu trữ trọn đời, bao gồm số phiên bản được lưu trữ cho các mẫu đã xóa. Nếu bạn xuất bản hơn 300 phiên bản mẫu trong suốt vòng đời của dự án thì các phiên bản sớm nhất sẽ bị xóa, duy trì tối đa 300 phiên bản.

Quản lý các phiên bản mẫu Cấu hình từ xa

Phần này mô tả cách quản lý các phiên bản của mẫu Cấu hình từ xa của bạn. Để biết thêm chi tiết về cách tạo, sửa đổi và lưu mẫu theo chương trình, hãy xem Sửa đổi cấu hình từ xa theo chương trình .

Liệt kê tất cả các phiên bản được lưu trữ của mẫu Cấu hình từ xa

Bạn có thể truy xuất danh sách tất cả các phiên bản được lưu trữ của mẫu Cấu hình từ xa. Ví dụ:

Node.js

function listAllVersions() {
  admin.remoteConfig().listVersions()
    .then((listVersionsResult) => {
      console.log("Successfully fetched the list of versions");
      listVersionsResult.versions.forEach((version) => {
        console.log('version', JSON.stringify(version));
      });
    })
    .catch((error) => {
      console.log(error);
    });
}

Java

ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
while (page != null) {
  for (Version version : page.getValues()) {
    System.out.println("Version: " + version.getVersionNumber());
  }
  page = page.getNextPage();
}

// Iterate through all versions. This will still retrieve versions in batches.
page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
for (Version version : page.iterateAll()) {
  System.out.println("Version: " + version.getVersionNumber());
}

NGHỈ NGƠI

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

Bảng điều khiển Firebase

Trong tab Tham số , chọn biểu tượng "đồng hồ" hiển thị ở trên cùng bên phải. Thao tác này sẽ mở trang Lịch sử thay đổi liệt kê tất cả các phiên bản mẫu được lưu trữ trong menu danh sách ở bên phải.

Thông tin chi tiết được hiển thị cho từng phiên bản được lưu trữ bao gồm thông tin về việc các thay đổi có nguồn gốc từ Bảng điều khiển, với API REST, từ quá trình khôi phục hay liệu chúng có phải là các thay đổi gia tăng từ việc buộc lưu mẫu hay không.

Firebase CLI

firebase remoteconfig:versions:list

Sử dụng tùy chọn --limit để giới hạn số lượng phiên bản được trả về. Vượt qua '0' để tìm nạp tất cả các phiên bản.

Danh sách các mẫu bao gồm siêu dữ liệu cho tất cả các phiên bản được lưu trữ, bao gồm cả thời gian cập nhật, người dùng đã tạo bản cập nhật đó và liệu bản cập nhật đó được tạo thông qua bảng điều khiển hay API REST. Đây là một ví dụ về phần tử phiên bản:

{
  "versions": [{
    "version_number": "6",
    "update_time": "2022-05-12T02:38:54Z",
    "update_user": {
      "name": "Jane Smith",
      "email": "jane@developer.org",
      "imageUrl": "https://lh3.googleusercontent.com/a-/..."
    },
    "description": "One small change on the console",
    "origin": "CONSOLE",
    "update_type": "INCREMENTAL_UPDATE"
  }]

Truy xuất phiên bản cụ thể của mẫu Cấu hình từ xa

Bạn có thể truy xuất bất kỳ phiên bản được lưu trữ cụ thể nào của mẫu Cấu hình từ xa. Ví dụ:

Node.js

Truyền getTemplate() mà không có bất kỳ đối số nào để truy xuất phiên bản mới nhất của mẫu hoặc để truy xuất một phiên bản cụ thể, hãy sử dụng getTemplateAtVersion() .

// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
  .then((template) => {
    console.log("Successfully fetched the template with ETag: " + template.etag);
  })
  .catch((error) => {
    console.log(error);
  });

Java

Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get();
// See the ETag of the fetched template.
System.out.println("Successfully fetched the template with ETag: " + template.getETag());

NGHỈ NGƠI

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig?version_number=6

Tham số URL ?version_number chỉ hợp lệ cho các hoạt động GET ; bạn không thể sử dụng nó để chỉ định số phiên bản cho các bản cập nhật. Một yêu cầu nhận tương tự không có tham ?version_number sẽ truy xuất mẫu đang hoạt động.

Bảng điều khiển Firebase

Theo mặc định, ngăn chi tiết trong tab Lịch sử thay đổi sẽ hiển thị mẫu hiện hoạt. Để xem chi tiết về phiên bản khác trong danh sách, hãy chọn phiên bản đó từ menu bên phải.

Bạn có thể xem sự khác biệt chi tiết của phiên bản hiện được chọn và bất kỳ phiên bản được lưu trữ nào khác bằng cách di chuột qua menu ngữ cảnh cho bất kỳ phiên bản nào không được chọn và chọn So sánh với phiên bản đã chọn.

Firebase CLI

firebase remoteconfig:get -v VERSION_NUMBER

Theo tùy chọn, bạn có thể ghi kết quả đầu ra vào một tệp được chỉ định bằng -o, FILENAME .

Quay lại phiên bản được lưu trữ cụ thể của mẫu Cấu hình từ xa

Bạn có thể quay lại bất kỳ phiên bản được lưu trữ nào của mẫu. Ví dụ:

Node.js

// Roll back to template version: 6
admin.remoteConfig().rollback('6')
  .then((template) => {
    console.log("Successfully rolled back to template version 6.");
    console.log("New ETag: " + template.etag);
  })
  .catch((error) => {
    console.log('Error trying to rollback:', e);
  })

Java

try {
  Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get();
  System.out.println("Successfully rolled back to template version: " + versionNumber);
  System.out.println("New ETag: " + template.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Error trying to rollback template.");
    System.out.println(rcError.getMessage());
  }
}

NGHỈ NGƠI

Để quay lại mẫu Cấu hình từ xa đã lưu trữ, hãy đưa ra HTTP POST bằng phương thức tùy chỉnh :rollback và trong phần nội dung yêu cầu, phiên bản cụ thể để áp dụng. Ví dụ:

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:rollback -d '{"version_number": 6}'

Phản hồi chứa nội dung của mẫu được lưu trữ hiện đang hoạt động, cùng với siêu dữ liệu phiên bản mới của nó.

Bảng điều khiển Firebase

Đối với các phiên bản mẫu trước đó đủ điều kiện để khôi phục, nút tùy chọn để quay lại phiên bản đó sẽ hiển thị ở trên cùng bên phải của trang Lịch sử thay đổi . Nhấp và xác nhận điều này chỉ khi bạn chắc chắn muốn quay lại phiên bản đó và sử dụng các giá trị đó ngay lập tức cho tất cả ứng dụng và người dùng.

Firebase CLI

firebase remoteconfig:rollback -v VERSION_NUMBER

Lưu ý rằng thao tác khôi phục này sẽ tạo ra một phiên bản được đánh số mới một cách hiệu quả. Ví dụ: quay lại từ phiên bản 10 sang phiên bản 6 sẽ tạo ra một bản sao mới của phiên bản 6 một cách hiệu quả, khác với bản gốc chỉ ở chỗ số phiên bản của nó là 11. Phiên bản 6 gốc vẫn được lưu trữ, giả sử nó chưa hết hạn và phiên bản 11 trở thành mẫu hoạt động.

Xóa mẫu Cấu hình từ xa

Bạn có thể xóa các mẫu Cấu hình từ xa khỏi bảng điều khiển Firebase. Để xóa mẫu Cấu hình từ xa:

  1. Từ trang Tham số cấu hình từ xa, nhấp vào sử thay đổi .

  2. Chuyển sang mẫu bạn muốn xóa, nhấp vào More , sau đó chọn Xóa .

  3. Khi được nhắc xác nhận việc xóa, hãy nhấp vào Xóa .

Tải xuống và xuất bản các mẫu Cấu hình từ xa

Tải xuống và xuất bản các mẫu Cấu hình từ xa để tích hợp chúng vào hệ thống xây dựng và kiểm soát nguồn của bạn, tự động cập nhật cấu hình cũng như giữ các tham số và giá trị được đồng bộ hóa trên nhiều dự án.

Bạn có thể tải xuống mẫu Cấu hình từ xa hiện đang hoạt động theo chương trình hoặc từ bảng điều khiển Firebase. Sau đó, bạn có thể cập nhật tệp JSON đã xuất và xuất bản nó lên cùng một dự án hoặc xuất bản nó lên một dự án mới hoặc dự án hiện có.

Giả sử bạn có nhiều dự án đại diện cho các giai đoạn khác nhau trong vòng đời phát triển phần mềm của mình, như môi trường phát triển, thử nghiệm, dàn dựng và sản xuất. Trong trường hợp này, bạn có thể quảng bá một mẫu đã được thử nghiệm đầy đủ từ môi trường chạy thử sang môi trường sản xuất bằng cách tải xuống mẫu đó từ dự án chạy thử và xuất bản nó lên dự án sản xuất của bạn.

Bạn cũng có thể sử dụng phương pháp này để di chuyển cấu hình từ dự án này sang dự án khác hoặc điền vào dự án mới các tham số và giá trị từ một dự án đã thiết lập.

Các thông số và giá trị thông số được tạo cụ thể dưới dạng biến thể trong thử nghiệm Thử nghiệm A/B không được đưa vào các mẫu đã xuất.

Để xuất và nhập mẫu Cấu hình từ xa:

  1. Tải xuống mẫu Cấu hình cấu hình từ xa hiện tại .
  2. Xác thực mẫu Cấu hình từ xa .
  3. Xuất bản mẫu Cấu hình từ xa .

Tải xuống Mẫu cấu hình từ xa hiện tại

Bạn có thể tải xuống mẫu Cấu hình từ xa hiện tại và đang hoạt động theo chương trình hoặc sử dụng bảng điều khiển Firebase.

Sử dụng các lệnh sau để tải xuống mẫu Cấu hình từ xa đang hoạt động ở định dạng JSON:

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

NGHỈ NGƠI

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

Lệnh này xuất tải trọng JSON thành một tệp và các tiêu đề (bao gồm ETag) thành một tệp headers riêng biệt.

Bảng điều khiển Firebase

  1. Từ tab Điều kiện hoặc Tham số Cấu hình Từ xa , hãy mở Menu và chọn Tải xuống tệp cấu hình hiện tại .
  2. Khi được nhắc, hãy nhấp vào Tải xuống tệp cấu hình , chọn vị trí bạn muốn lưu tệp, sau đó nhấp vào Lưu .

Firebase CLI

firebase remoteconfig:get -o filename

Xác thực mẫu Cấu hình từ xa

Bạn có thể xác thực các bản cập nhật mẫu của mình trước khi xuất bản chúng bằng SDK quản trị Firebase hoặc API REST. Các mẫu cũng được xác thực khi bạn cố gắng xuất bản từ bảng điều khiển Firebase CLI hoặc Firebase.

Quá trình xác thực mẫu sẽ kiểm tra các lỗi như khóa trùng lặp cho tham số và điều kiện, tên điều kiện không hợp lệ hoặc điều kiện không tồn tại hoặc Thẻ ETag bị định dạng sai. Ví dụ: một yêu cầu chứa nhiều hơn số lượng khóa được phép—2000—sẽ trả về thông báo lỗi, Param count too large .

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

NGHỈ NGƠI

Xác thực các bản cập nhật mẫu bằng cách thêm tham số URL ?validate_only=true vào yêu cầu xuất bản của bạn:

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?validate_only=true -d @filename

Nếu mẫu của bạn được xác thực thành công, lệnh cuộn tròn sẽ trả về mẫu JSON mà bạn đã gửi và trong tệp headers đã lưu, bạn sẽ tìm thấy trạng thái HTTP/2 200 và ETag được cập nhật có hậu tố -0 . Nếu mẫu của bạn không được xác thực, bạn sẽ nhận được lỗi xác thực trong phản hồi JSON và tệp headers của bạn sẽ chứa phản hồi không phải 200 (và không có ETag).

Xuất bản mẫu Cấu hình từ xa

Sau khi tải mẫu xuống, thực hiện mọi thay đổi cần thiết đối với nội dung JSON và xác thực nó, bạn có thể xuất bản mẫu đó lên một dự án.

Việc xuất bản mẫu sẽ thay thế toàn bộ mẫu cấu hình hiện có bằng tệp được cập nhật và tăng phiên bản mẫu lên một. Vì toàn bộ cấu hình được thay thế nên nếu bạn xóa một tham số khỏi tệp JSON và xuất bản nó, thì tham số đó sẽ bị xóa khỏi máy chủ và không còn khả dụng cho khách hàng.

Sau khi xuất bản, các thay đổi về thông số và giá trị sẽ có sẵn ngay lập tức cho ứng dụng và người dùng của bạn. Nếu cần, bạn có thể quay lại phiên bản trước .

Sử dụng các lệnh sau để xuất bản mẫu của bạn:

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

NGHỈ NGƠI

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

Đối với lệnh curl này, bạn có thể chỉ định nội dung bằng cách sử dụng ký tự "@", theo sau là tên tệp.

Bảng điều khiển Firebase

  1. Từ tab Điều kiện hoặc Tham số cấu hình từ xa , hãy mở Menu và chọn Xuất bản từ tệp .
  2. Khi được nhắc, hãy nhấp vào Duyệt , điều hướng đến và chọn tệp Cấu hình từ xa mà bạn muốn xuất bản, sau đó nhấp vào Chọn .
  3. Tệp sẽ được xác thực và nếu thành công, bạn có thể nhấp vào Xuất bản để cung cấp cấu hình ngay lập tức cho ứng dụng và người dùng của bạn.

Các điều kiện và cá nhân hóa Cấu hình từ xa được bao gồm trong các mẫu đã tải xuống, vì vậy điều quan trọng là phải biết những hạn chế sau đây khi cố gắng xuất bản lên một dự án khác:

  • Không thể nhập các cá nhân hóa từ dự án này sang dự án khác.

    Ví dụ: nếu bạn đã bật tính năng cá nhân hóa trong dự án của mình và tải xuống cũng như chỉnh sửa mẫu, bạn có thể xuất bản mẫu đó lên cùng một dự án nhưng không thể xuất bản nó sang một dự án khác trừ khi bạn xóa các cá nhân hóa khỏi mẫu.

  • Bạn có thể nhập các điều kiện từ dự án này sang dự án khác nhưng lưu ý rằng mọi giá trị điều kiện cụ thể (như mã ứng dụng hoặc đối tượng) đều phải tồn tại trong dự án mục tiêu trước khi xuất bản.

    Ví dụ: nếu bạn có tham số Cấu hình từ xa sử dụng điều kiện chỉ định giá trị nền tảng là iOS thì mẫu có thể được xuất bản cho một dự án khác vì các giá trị nền tảng đều giống nhau đối với mọi dự án. Tuy nhiên, nếu nó chứa một điều kiện dựa trên ID ứng dụng cụ thể hoặc đối tượng người dùng không tồn tại trong dự án mục tiêu thì quá trình xác thực sẽ không thành công.

  • Nếu mẫu bạn dự định xuất bản chứa các điều kiện dựa vào Google Analytics thì Analytics phải được bật trong dự án mục tiêu.

Tải xuống mặc định mẫu Cấu hình từ xa

Vì ứng dụng của bạn có thể không phải lúc nào cũng được kết nối với Internet nên bạn nên định cấu hình các giá trị mặc định của ứng dụng phía máy khách cho tất cả các tham số Cấu hình từ xa. Bạn cũng nên đồng bộ hóa định kỳ các giá trị mặc định của ứng dụng khách và giá trị tham số mặc định của phần phụ trợ Cấu hình từ xa vì chúng có thể thay đổi theo thời gian.

Như được mô tả trong các liên kết dành riêng cho nền tảng ở cuối phần này, bạn có thể đặt các giá trị mặc định này theo cách thủ công trong ứng dụng của mình hoặc bạn có thể hợp lý hóa quy trình này bằng cách tải xuống các tệp chỉ chứa các cặp khóa-giá trị cho tất cả tham số và giá trị mặc định của chúng trong mẫu Cấu hình từ xa đang hoạt động. Sau đó, bạn có thể đưa tệp này vào dự án của mình và định cấu hình ứng dụng của mình để nhập các giá trị này.

Bạn có thể tải xuống các tệp này ở định dạng XML cho ứng dụng Android, định dạng danh sách thuộc tính (plist) cho ứng dụng iOS và JSON cho ứng dụng web.

Chúng tôi khuyên bạn nên tải xuống định kỳ các giá trị mặc định của Cấu hình từ xa trước khi phát hành bất kỳ ứng dụng mới nào để đảm bảo rằng ứng dụng của bạn và chương trình phụ trợ Cấu hình từ xa luôn được đồng bộ hóa.

Để tải xuống tệp chứa các giá trị mặc định của mẫu:

NGHỈ NGƠI

curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'

Sử dụng XML , PLIST hoặc JSON làm giá trị format , tùy thuộc vào định dạng tệp bạn muốn tải xuống.

Bảng điều khiển Firebase

  1. Trong tab Tham số , mở Menu và chọn Tải xuống các giá trị mặc định .
  2. Khi được nhắc, hãy nhấp vào nút radio tương ứng với định dạng tệp bạn muốn tải xuống, sau đó nhấp vào Tải xuống tệp .

Để biết thêm thông tin về cách nhập các giá trị mặc định của Cấu hình từ xa vào ứng dụng của bạn, hãy xem: