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

Mẫu Cấu hình từ xa là các tập hợp các thông số và điều kiện 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 ứng dụng mà từ đó ứng dụng của bạn tìm nạp giá trị và mẫu máy chủ mà từ đó ứng dụng 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 cách sử dụng bảng điều khiển của 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à Điều kiện. Bạn cũng có thể dùng API REST cho cấu hình từ xa và SDK quản trị hoặc Giao diện dòng lệnh (CLI) của Firebase để sửa đổi và quản lý mẫu ứng dụng.

Dưới đây là ví dụ về một tệp mẫu ứng dụng:

      {
        "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"
        }
      }

Dưới đây là ví dụ về một 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 sau bằng bảng điều khiển của Firebase:

• Liệt kê tất 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á các mẫu Cấu hình từ xa trên trang Nhật ký thay đổi

Nếu đang quản lý mẫu ứng dụng, bạn cũng có thể liệt kê mẫu, truy xuất mẫu và khôi phục mẫu bằng cách sử dụng Firebase CLI và API phụ trợ Cấu hình từ xa.

Mỗi loại mẫu có tổng giới hạn 300 phiên bản được lưu trữ trong suốt thời gian hoạt động (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 một dự án, thì các phiên bản đầu tiên sẽ bị xoá và duy trì tối đa 300 phiên bản của loại đó.

Mỗi lần bạn cập nhật thông số, Cấu hình từ xa sẽ tạo một mẫu Cấu hình từ xa có 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 khôi phục khi cần. Số phiên bản tăng tuần tự từ giá trị ban đầu do Cấu hình từ xa 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ể đó.

Với bảng điều khiển của Firebase, Giao diện dòng lệnh (CLI) của Firebase 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 đây:

• Liệt kê tất 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 cụ thể

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

Quản lý 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. Để biết thêm thông tin chi tiết về cách tạo, sửa đổi và lưu mẫu theo phương thức lập trình, hãy xem phần Sửa đổi Cấu hình từ xa theo phương thức lập trình.

Liệt kê tất cả phiên bản đã 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ả phiên bản đã lưu trữ của mẫu Cấu hình từ xa. Ví dụ:

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

firebase remoteconfig:versions:list

Danh sách mẫu bao gồm siêu dữ liệu cho mọi phiên bản đã lưu trữ, bao gồm cả thời điểm cập nhật, người dùng tạo ra mẫu đó và việc mẫu cập nhật được tạo thông qua bảng điều khiển hay API REST. Dưới đây là 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ụ thể nào được lưu trữ của mẫu Cấu hình từ xa. Ví dụ:

// 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

firebase remoteconfig:get -v VERSION_NUMBER

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

Bạn có thể khôi phục về bất kỳ phiên bản mẫu nào đã lưu trữ. Ví dụ:

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

firebase remoteconfig:rollback -v VERSION_NUMBER

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 một cách hiệu quả. Ví dụ: việc khôi phục 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 một cách hiệu quả, khác với bản gốc chỉ ở chỗ số phiên bản là 11. Phiên bản gốc 6 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 Cấu hình từ xa

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

1. Trên trang Thông số của Cấu hình từ xa, hãy nhấp vào history Nhật ký thay đổi.

2. Chuyển đến mẫu bạn muốn xoá, nhấp vào more_vertLựa chọn khác, rồi chọn Xoá.

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

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

Tải xuống và phát hành các mẫu Cấu hình từ xa để tích hợp các mẫu đó 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, đồng thời luôn đồng bộ hoá các tham số và giá trị trên nhiều dự án.

Bạn có thể tải mẫu Cấu hình từ xa hiện đang hoạt động xuống theo phương thức lập trình hoặc từ bảng điều khiển của Firebase. Sau đó, bạn có thể cập nhật tệp JSON đã xuất và phát hành lên cùng một dự án, hoặc phát hành lên 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à sản xuất. Trong trường hợp này, bạn có thể quảng bá một mẫu đã thử nghiệm đầy đủ từ môi trường thử nghiệm lên môi trường phát hành chính thức bằng cách tải mẫu đó xuống từ dự án thử nghiệm và phát hành lên dự án phát hành chính thức.

Bạn cũng có thể sử dụng phương thức này để di chuyển các 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ừ dự án đã có vào dự án mới.

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

Cách xuất và nhập các mẫu Cấu hình từ xa:

1. Tải mẫu Cấu hình từ xa hiện có xuống.
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 mẫu Cấu hình từ xa hiện tại xuống

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

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

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

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 nội dung cập nhật mẫu trước khi xuất bản bằng cách sử dụng SDK dành cho quản trị viên 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 CLI của Firebase hoặc Firebase.

Quy trình xác thực mẫu sẽ kiểm tra các lỗi, chẳng hạn như các tham số và điều kiện trùng lặp, tên điều kiện không hợp lệ hoặc điều kiện không tồn tại hay ETag bị định dạng sai. Ví dụ: yêu cầu chứa nhiều hơn số lượng khoá cho 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 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 mẫu đó, bạn có thể phát hành mẫu đó lên 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 lên một phần. 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 rồi xuất bản, thì tham số đó sẽ bị xoá khỏi máy chủ và không còn được cung cấp cho ứng dụng.

Sau khi phát hành, các thay đổi đối với tham số và giá trị sẽ ngay được cung cấp cho ứng dụng và người dùng của bạn. Nếu cần, bạn có thể hoàn nguyên về phiên bản trước đó.

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

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

Hoạt động cá nhân hoá và điều kiện Cấu hình từ xa có trong các mẫu đã tải xuống, vì vậy, bạn cần lưu ý đến các điểm hạn chế sau đây khi tìm cách phát hành lên một dự án khác:

• Không thể nhập các 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 đồng thời tải xuống và chỉnh sửa mẫu, bạn có thể phát hành mẫu đó lên cùng một dự án, nhưng không thể xuất bản lên một dự án khác trừ phi bạn xoá nội dung 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ể (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ó 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 phát hành lên một dự án khác, vì các giá trị nền tảng là như 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 một mã ứ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ì việc xác thực sẽ không thành công.

• Nếu mẫu mà 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 mẫu Cấu hình từ xa xuống chế độ mặc định

Vì không phải lúc nào ứng dụng cũng kết nối được 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 định kỳ đồng bộ hoá các giá trị mặc định của ứng dụng ứng dụng và các giá trị thông số mặc định của phần phụ trợ Cấu hình từ xa, 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 đơn giản hoá quy trình này bằng cách tải các tệp chỉ chứa cặp khoá-giá trị cho tất cả các thông 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 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 của Cấu hình từ xa xuống trước mọi bản phát hành ứng dụng mới để đảm bảo ứng dụng và phần phụ trợ Cấu hình từ xa luôn đồng bộ hoá.

Cách tải một tệp chứa mẫu mặc định 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 các giá trị mặc định của Cấu hình từ xa vào ứng dụng, hãy xem:

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

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

• Đặt giá trị thông 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++