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 (client) 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 giá trị.

Bạn sẽ 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ẻ Thông số và Điều kiện. Bạn cũng có thể sử dụng API REST Cấu hình từ xa và SDK dành cho quản trị viên hoặc Firebase CLI để sửa đổi và quản lý mẫu ứng dụng của mình.

Dưới đây là ví dụ về 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ề 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ề phiên bản ứng dụng cụ thể
• Xoá mẫu Cấu hình từ xa khỏi trang Nhật ký thay đổi

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

Có tổng giới hạn 300 phiên bản được lưu trữ trong thời gian hoạt động 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 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 sẽ tăng tuần tự từ giá trị ban đầu được 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ể đó.

Thông qua bảng điều khiển của Firebase, Firebase CLI hoặc API phụ trợ Cấu hình từ xa, bạn có thể thực hiện các thao tác 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á 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 là 300 phiên bản được lưu trữ trong thời gian hoạt động, 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 trong suốt vòng đời của một dự án, thì các phiên bản sớm nhất sẽ bị xoá, giúp 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 được lưu trữ, bao gồm cả thời điểm cập nhật, người dùng đã tạo và việc liệu sản phẩm đượ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 mọi phiên bản cụ thể đượ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 đã lưu trữ nào. 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 sang phiên bản 6 sẽ tạo ra bản sao mới của phiên bản 6 một cách hiệu quả, chỉ khác với 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 chưa hết hạn và phiên bản 11 trở thành mẫu hoạt động.

Xoá mẫu Cấu hình từ xa

Bạn có thể xoá 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ấu hình từ xa, hãy nhấp vào history Nhật ký thay đổi.

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

3. Khi được nhắc xác nhận thao tác 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 và phát hành mẫu Cấu hình từ xa để tích hợp vào hệ thống xây dựng và kiểm soát nguồn, tự động cập nhật cấu hình, đồng thời đồ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 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 tệp đó lên cùng một dự án, hoặc phát hành tệp đó lên một dự án mới hoặc dự án hiện có.

Giả sử bạn có nhiều dự án thể hiện 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ử, chạy thử và phát hành chính thức. 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 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 rồi phát hành mẫu đó 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ấu hình từ dự án này sang dự án khác hoặc điền sẵn các 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 thông số và giá trị thông số được tạo cụ thể dưới dạng biến thể trong một thử nghiệm Thử nghiệm A/B không được đưa vào các mẫu đã xuất.

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

1. Tải mẫu Cấu hình từ xa hiện tại 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 thông qua bảng điều khiển của Firebase.

Sử 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 Quản trị của 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 trong bảng điều khiển của Firebase CLI hoặc Firebase.

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 cho phép (2000 khoá) 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ộ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 mẫu đó, bạn có thể xuất bản mẫu đó 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 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à xuất bản tham số đó, thì tham số đó sẽ bị xoá khỏi máy chủ và không còn hiển thị cho ứng dụng khách.

Sau khi phát hành, các thay đổi đối với tham số và giá trị sẽ xuất hiệ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ể khôi phục về 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

Các hoạt động cá nhân hoá và điều kiện của 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 ý các giới hạn 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 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 cũng như tải xuống và chỉnh sửa một mẫu, thì bạn có thể phát hành mẫu đó lên cùng dự án, nhưng không thể phát hành mẫu đó lên một dự án khác trừ phi bạn xoá các hoạt độ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ể (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 có thông số Cấu hình từ xa sử dụng một điều kiện chỉ định giá trị nền tảng là iOS, thì bạn có thể phát hành mẫu cho một dự án khác vì các giá trị nền tảng giống nhau đối với mọi dự án. Tuy nhiên, nếu tệp này chứa một đ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 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 định xuất bản có chứa các điều kiện phụ thuộc vào Google Analytics, thì bạn phải bật Analytics trong dự án mục tiêu.

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

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

Cách tải tệp có chứa 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 của Cấu hình từ xa 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ị 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++