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 tham số và điều kiện có định dạng JSON mà bạn đã tạo cho dự án Firebase. Bạn có thể tạo mẫu máy khách để ứng dụng của bạn tìm nạp giá trị và mẫu máy chủ để máy khách máy chủ có thể tìm nạp 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 hiển thị nội dung của mẫu ở định dạng đồ hoạ trong thẻThẻ Parameters (Tham số) và Conditions (Điều kiện).

Bạn cũng có thể sử dụng API REST Remote Config và SDK dành cho quản trị viên hoặc CLI Firebase để sửa đổi và quản lý mẫu ứng dụng.

Dưới đây là ví dụ về tệp mẫu 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ả phiên bản mẫu được 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 số phiên bản được lưu trữ trong vòng đời là 300 phiên bản cho mỗi loại mẫu (300 mẫu ứng dụng và 300 mẫu máy chủ), bao gồm cả số phiên bản được lưu trữ cho các mẫu đã xoá. Nếu bạn phát hành hơn 300 phiên bản mẫu cho mỗi loại mẫu trong suốt thời gian hoạt động của 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 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 nếu cần. Số phiên bản được tăng dần theo tuần tự từ giá trị ban đầu do Remote Config lưu trữ. Tất cả các mẫu đều có 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 đổi của 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ả phiên bản đã lưu của mẫu Remote Config

Bạn có thể truy xuất danh sách tất 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ả 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 và cách tạo phiên bản. Dưới đây là ví dụ về 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 được lưu trữ của mẫu Remote Config. Cách truy xuấ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 trữ của mẫu Remote Config

Bạn có thể quay lại bất kỳ phiên bản mẫu nào đã lưu trữ. 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 một phiên bản được đánh số mới một cách hiệu quả. Ví dụ: việc quay lại từ phiên bản 10 về phiên bản 6 sẽ tạo một bản sao mới của phiên bản 6, chỉ khác với phiên bản gốc ở chỗ số phiên bản là 11. Phiên bản gốc 6 vẫn được lưu trữ, giả sử phiên bản này chưa hết hạn và phiên bản 11 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 xoá, hãy nhấp vào Xoá.

Tải xuống và phát hành mẫu Remote Config

Tải xuống và phát hành các mẫu Remote Config để tích hợp các mẫu đó vào hệ thống kiểm soát nguồn và xây dựng, tự động hoá việc cập nhật cấu hình cũng như đồng bộ hoá các thông số và giá trị trên nhiều dự án.

Bạn có thể tải mẫu Remote Config đang hoạt động xuống bằng 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à phát hành tệp đó cho cùng một dự án hoặc phát hành tệp đó cho một dự án mới hoặc 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ử, thử nghiệm 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 thử nghiệm sang môi trường phát hành công khai bằng cách tải mẫu đó xuống từ dự án thử nghiệm và phát hành mẫu đó sang dự án phát hành công khai.

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 các tham số và giá trị từ một dự án đã thiết lập vào 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 thử nghiệm A/B Testing sẽ không có trong mẫu đã xuất.

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

1. Tải mẫu Cấu hình Remote Config 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

Hãy sử dụng mã 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 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 có định dạng không chính xác. Ví dụ: một yêu cầu chứa nhiều hơn số lượng khoá được phép (2000) 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ể phát hành mẫu đó cho một dự án.

Việc phát hành 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 được thay thế, nên nếu bạn xoá một tham số khỏi tệp JSON và phát hành tham số đó, thì tham số đó sẽ bị xoá khỏi máy chủ và không còn được cung cấp cho ứng dụng nữa.

Sau khi phát hành, các thay đổi đối với thông số và giá trị sẽ ngay lập tức có sẵn cho ứng dụng và người dùng. 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 để phát hành 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

Các điều kiện và thông tin cá nhân hoá Remote Config đượ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 phát hành cho một dự án khác:

• Bạn không thể nhập nội dung 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ể phát hành mẫu đó cho cùng một dự án, nhưng không thể phát hành mẫu đó cho một dự án khác trừ phi 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ị có điều kiện cụ thể (chẳng hạn như mã ứng dụng hoặc đối tượng) phải tồn tại trong dự án mục tiêu trước khi phát hành.

  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ì mẫu có thể được phát hành cho một dự án khác, vì giá trị nền tảng giống nhau đối với mọi dự án. Tuy nhiên, nếu chứa một điều kiện dựa trên mã ứng dụng hoặc đối tượng người dùng cụ thể 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 phát hành 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 các mẫu mặc định của Remote Config xuống

Vì ứng dụng của bạn không phải lúc nào cũng 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ố 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à giá trị tham số mặc định của phần phụ trợ Remote Config, vì các giá trị này 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 bạn có thể đơn giản hoá quy trình này bằng cách tải các tệp chứa chỉ các cặp khoá-giá trị cho tất 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 tải các giá trị mặc định của Remote Config xuống định kỳ trước khi phát hành ứng dụng mới để đảm bảo ứng dụng 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++