Tạo phiên bản và mẫu Cấu hình từ xa

Mẫu Remote Config là tập hợp các điều kiện và thông số được định dạng JSON mà bạn đã tạo cho dự án Firebase của mình. Bạn có thể tạo mẫu máy khách (từ đó ứng dụng của bạn tìm nạp các giá trị) và mẫu máy chủ (từ đó máy khách máy chủ có thể tìm nạp các giá trị).

Bạn 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 sẽ hiển thị nội dung của mẫu ở định dạng đồ hoạ trong các thẻ Tham số và thẻ Điều kiện.

Bạn cũng có thể sử dụng Remote Config REST API và Admin SDK hoặc Firebase CLI để sửa đổi và quản lý mẫu ứng dụng khách.

Sau đây là ví dụ về một tệp mẫu phía máy chủ:

{
  "parameters": {
    "preamble_prompt": {
      "defaultValue": {
        "value": "You are a helpful assistant who knows everything there is to know about Firebase! "
      },
      "description": "Add this prompt to the user's prompt",
      "valueType": "STRING"
    },
    "model_name": {
      "defaultValue": {
        "value": "gemini-pro-test"
      },
      "valueType": "STRING"
    },
    "generation_config": {
      "defaultValue": {
        "value": "{\"temperature\": 0.9, \"maxOutputTokens\": 2048, \"topP\": 0.9, \"topK\": 20}"
      },
      "valueType": "JSON"
    },
  },
  "version": {
    "versionNumber": "19",
    "isLegacy": true
  }
}

Bạn có thể thực hiện các tác vụ quản lý phiên bản này bằng bảng điều khiển Firebase:

• Liệt kê tất cả các phiên bản mẫu đã lưu trữ
• Truy xuất một phiên bản cụ thể
• Khôi phục về một phiên bản ứng dụng cụ thể
• Xoá mẫu Remote Config khỏi trang Nhật ký thay đổi

Tổng cộng có tối đa 300 phiên bản được lưu trữ trong suốt thời gian tồn tại cho mỗi loại mẫu (300 mẫu phía máy khách và 300 mẫu phía máy chủ), bao gồm cả số phiên bản được lưu trữ cho các mẫu đã bị xoá. Nếu bạn xuất bản hơn 300 phiên bản mẫu cho mỗi loại mẫu trong suốt thời gian tồn tại của một dự án, thì các phiên bản sớm nhất sẽ bị xoá, duy trì tối đa 300 phiên bản của loại đó.

Mỗi khi bạn cập nhật các tham số, Remote Config sẽ tạo một mẫu Remote Config mới có phiên bản và lưu trữ mẫu trước đó dưới dạng một 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 do Remote Config lưu trữ. Tất cả các mẫu đều có một trường version như minh hoạ, chứa siêu dữ liệu về phiên bản cụ thể đó.

Bạn có thể xoá các mẫu Remote Config khi cần trên trang Nhật ký thay đổitrên bảng điều khiển Remote Config.

Quản lý các phiên bản mẫu Remote Config

Phần này mô tả cách quản lý các phiên bản của mẫu Remote Config.

Liệt kê tất cả các phiên bản đã lưu trữ của mẫu Remote Config

Bạn có thể truy xuất danh sách tất cả các phiên bản đã lưu của mẫu Remote Config. Để thực hiện việc này:

firebase remoteconfig:versions:list

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

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

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

Danh sách mẫu bao gồm siêu dữ liệu cho tất cả các phiên bản đã lưu trữ, bao gồm cả thời gian cập nhật, người dùng đã thực hiện và cách thực hiện. Sau đây là ví dụ về một phần tử phiên bản:

```json
{
  "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 một phiên bản cụ thể của mẫu Remote Config

Bạn có thể truy xuất bất kỳ phiên bản cụ thể nào đã lưu trữ của mẫu Remote Config. Cách truy xuất một phiên bản mẫu đã lưu trữ:

firebase remoteconfig:get -v VERSION_NUMBER

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

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

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

Khôi phục về một phiên bản cụ thể đã lưu của mẫu Remote Config

Bạn có thể khôi phục về bất kỳ phiên bản nào đã lưu của mẫu. Cách khôi phục mẫu:

firebase remoteconfig:rollback -v VERSION_NUMBER

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

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

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}'

Xin 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. Ví dụ: việc quay lại từ phiên bản 10 về phiên bản 6 sẽ tạo ra một bản sao mới của phiên bản 6, chỉ khác với bản gốc ở chỗ số phiên bản là 11. Phiên bản 6 ban đầu vẫn được lưu trữ (giả sử chưa hết hạn) và phiên bản 11 sẽ trở thành mẫu đang hoạt động.

Xoá mẫu Remote Config

Bạn có thể xoá các mẫu Remote Config khỏi bảng điều khiển Firebase. Cách xoá mẫu Remote Config:

1. Chuyển đến mẫu bạn muốn xoá, nhấp vào biểu tượng more_vertTuỳ chọn khác, rồi chọn Xoá.

2. Khi được nhắc xác nhận việc xoá, hãy nhấp vào Xoá.

Tải xuống và xuất bản mẫu Remote Config

Tải xuống và xuất bản các mẫu Remote Config để tích hợp chúng vào hệ thống kiểm soát nguồn và hệ thống tạo bản dựng, tự động hoá các bản cập nhật cấu hình, đồng thời giữ cho các thông số và giá trị luôn đồng bộ trên nhiều dự án.

Bạn có thể tải mẫu Remote Config hiện đang hoạt động xuống theo cách lập trìnhtừ 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 tệp đó vào cùng một dự án hoặc xuất bản tệp đó vào 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, chẳng hạn như môi trường phát triển, kiểm thử, dàn dựng và phát hành công khai. Trong trường hợp này, bạn có thể quảng bá một mẫu đã được kiểm thử đầy đủ từ môi trường dàn dựng sang môi trường thực tế bằng cách tải mẫu đó xuống từ dự án dàn dựng và xuất bản mẫu đó sang dự án thực tế.

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

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

Cách xuất và nhập mẫu Remote Config:

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

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

Sử dụng nội dung sau để tải mẫu Remote Config đang hoạt động xuống ở định dạng JSON:

firebase remoteconfig:get -o filename

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

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

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

Quy trình xác thực mẫu sẽ kiểm tra các lỗi như khoá trùng lặp cho các 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 ETag bị định dạng sai. Ví dụ: một yêu cầu chứa nhiều hơn số lượng khoá được phép (2.000) sẽ trả về thông báo lỗi Param count too large.

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

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

Xuất bản mẫu Remote Config

Sau khi tải một 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ội dung đó, bạn có thể xuất bản nội dung đó lên một dự án.

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

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

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

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

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

Remote Config và điều kiện cá nhân hoá được đưa vào các mẫu đã tải xuống, vì vậy, bạn cần lưu ý những hạn chế sau đây khi cố gắng xuất bản sang một dự án khác:

• Bạn không thể nhập hoạt động cá nhân hoá từ dự án này sang dự án khác.

  Ví dụ: nếu đã bật tính năng cá nhân hoá trong dự án và tải xuống cũng như chỉnh sửa một mẫu, bạn có thể xuất bản mẫu đó vào cùng dự án, nhưng không thể xuất bản vào một dự án khác, trừ phi bạn xoá tính năng cá nhân hoá 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ể (chẳng hạn như mã ứng dụng hoặc đối tượng) phải có trong dự án mục tiêu trước khi xuất bản.

  Ví dụ: nếu bạn có một tham số Remote Config sử dụng một điều kiện chỉ định giá trị nền tảng là iOS, thì bạn có thể xuất bản mẫu này sang một dự án khác vì giá trị nền tảng là như nhau đối với mọi dự án. Tuy nhiên, nếu điều kiện đó dựa vào một mã ứng dụng hoặc đối tượng người dùng cụ thể không có 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 mà bạn dự định xuất bản có chứa các điều kiện dựa trên Google Analytics, thì bạn phải bật Analytics trong dự án mục tiêu.

Tải mẫu Remote Config mặc định xuống

Vì ứng dụng của bạn có thể không phải lúc nào cũng kết nối với Internet, nên bạn phải đị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ố Remote Config. Bạn cũng nên định kỳ đồng bộ hoá các giá trị mặc định của ứng dụng và các giá trị tham số mặc định của phần phụ trợ Remote Config, vì chúng có thể thay đổi theo thời gian.

Như mô tả trong các đường 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 hoặc có thể đơn giản hoá quy trình này bằng cách tải các tệp xuống. Các tệp này chỉ chứa các cặp khoá-giá trị cho tất cả các tham số và giá trị mặc định của các tham số đó trong mẫu Remote Config đang hoạt động. Sau đó, bạn có thể đưa tệp này vào dự án và định cấu hình ứng dụng để nhập các giá trị này.

Bạn có thể tải các tệp này xuống ở đị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.

Bạn nên định kỳ tải các giá trị mặc định Remote Config xuống trước khi phát hành bất kỳ ứng dụng mới nào để đảm bảo ứng dụng của bạn và phần phụ trợ Remote Config luôn đồng bộ.

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

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

Để biết thêm thông tin về cách nhập giá trị mặc định Remote Config vào ứng dụng, hãy xem:

• Đặt giá trị tham số mặc định trong ứng dụng cho Android

• Đặt giá trị tham số mặc định trong ứng dụng cho iOS

• Đặt giá trị tham số mặc định trong ứng dụng cho Web

• Đặt giá trị tham số mặc định trong ứng dụng cho Unity

• Đặt giá trị tham số mặc định trong ứng dụng cho C++