Sửa đổi Cấu hình từ xa theo phương thức lập trình

Tài liệu này mô tả cách bạn có thể đọc và sửa đổi tập hợp các tham số và điều kiện có định dạng JSON được gọi là mẫu Remote Config theo phương thức lập trình. Điều này cho phép bạn thực hiện các thay đổi về mẫu trên phần phụ trợ mà ứng dụng khách có thể tìm nạp bằng cách sử dụng thư viện ứng dụng khách.

Khi sử dụng Remote Config REST API hoặc Admin SDK được mô tả trong hướng dẫn này, bạn có thể bỏ qua việc quản lý mẫu trong bảng điều khiển Firebase để trực tiếp tích hợp các thay đổi về Remote Config vào quy trình của riêng mình. Ví dụ: với các API phụ trợ Remote Config, bạn có thể:

• Lập lịch cập nhật Remote Config. Bằng cách sử dụng lệnh gọi API kết hợp với công việc cron, bạn có thể thay đổi các giá trị Remote Config theo lịch trình thông thường.
• Nhập hàng loạt giá trị cấu hình để chuyển đổi hiệu quả từ hệ thống độc quyền của riêng bạn sang Firebase Remote Config.

• Sử dụng Remote Config với Cloud Functions for Firebase, thay đổi các giá trị trong ứng dụng dựa trên các sự kiện xảy ra phía máy chủ. Ví dụ: bạn có thể sử dụng Remote Config để quảng bá một tính năng mới trong ứng dụng, sau đó tự động tắt quảng bá đó sau khi phát hiện đủ người đã tương tác với tính năng mới.

  

Các phần sau của hướng dẫn này mô tả các thao tác bạn có thể thực hiện với API phụ trợ Remote Config. Để xem lại một số mã thực hiện các tác vụ này thông qua API REST, hãy xem một trong các ứng dụng mẫu sau:

• Bắt đầu nhanh với API REST Cấu hình từ xa Firebase bằng Java
• Bắt đầu nhanh với Node.js cho API REST của Cấu hình từ xa Firebase
• Bắt đầu nhanh bằng Python cho API REST Cấu hình từ xa Firebase

Sửa đổi Cấu hình từ xa bằng SDK Quản trị Firebase

Admin SDK là một bộ thư viện máy chủ cho phép bạn tương tác với Firebase từ các môi trường đặc quyền. Ngoài việc thực hiện các bản cập nhật cho Remote Config, Admin SDK còn cho phép tạo và xác minh mã thông báo xác thực Firebase, đọc và ghi từ Realtime Database, v.v. Để tìm hiểu thêm về các điều kiện tiên quyết và cách thiết lập Admin SDK, hãy xem phần Thêm SDK quản trị Firebase vào máy chủ.

Trong quy trình Remote Config thông thường, bạn có thể lấy mẫu hiện tại, sửa đổi một số thông số hoặc nhóm thông số và điều kiện, xác thực mẫu rồi phát hành mẫu đó. Trước khi thực hiện các lệnh gọi API đó, bạn phải uỷ quyền cho các yêu cầu từ SDK.

Khởi chạy SDK và uỷ quyền cho các yêu cầu API

Khi bạn khởi tạo Admin SDK mà không có tham số nào, SDK sẽ sử dụng Thông tin xác thực mặc định của ứng dụng Google và đọc các tuỳ chọn từ biến môi trường FIREBASE_CONFIG. Nếu nội dung của biến FIREBASE_CONFIG bắt đầu bằng {, thì nội dung đó sẽ được phân tích cú pháp dưới dạng đối tượng JSON. Nếu không, SDK sẽ giả định rằng chuỗi đó là tên của tệp JSON chứa các tuỳ chọn.

Ví dụ:

const admin = require('firebase-admin');
admin.initializeApp();

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

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

Khi làm việc với các mẫu Remote Config, hãy lưu ý rằng các mẫu này được tạo phiên bản và mỗi phiên bản có thời hạn sử dụng giới hạn từ thời điểm tạo đến thời điểm bạn thay thế phiên bản đó bằng một bản cập nhật: 90 ngày, với tổng hạn mức là 300 phiên bản được lưu trữ. Hãy xem phần Mẫu và phiên bản để biết thêm thông tin.

Bạn có thể sử dụng các API phụ trợ để lấy phiên bản đang hoạt động hiện tại của mẫu Remote Config ở định dạng JSON.

Các thông số và giá trị thông 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 tải mẫu:

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

Sửa đổi thông số Cấu hình từ xa

Bạn có thể sửa đổi và thêm các tham số Remote Config và nhóm tham số theo phương thức lập trình. Ví dụ: đối với một nhóm thông số hiện có có tên là "new_menu", bạn có thể thêm một thông số để kiểm soát việc hiển thị thông tin theo mùa:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

API cho phép bạn tạo các tham số và nhóm tham số mới hoặc sửa đổi giá trị mặc định, giá trị có điều kiện và nội dung mô tả. Trong mọi trường hợp, bạn phải phát hành mẫu một cách rõ ràng sau khi chỉnh sửa.

Sửa đổi các điều kiện của Cấu hình từ xa

Bạn có thể sửa đổi và thêm các điều kiện Remote Config và giá trị có điều kiện theo phương thức lập trình. Ví dụ: cách thêm một điều kiện mới:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

Trong mọi trường hợp, bạn phải phát hành mẫu một cách rõ ràng sau khi chỉnh sửa.

API phụ trợ Remote Config cung cấp một số điều kiện và toán tử so sánh mà bạn có thể sử dụng để thay đổi hành vi và giao diện của ứng dụng. Để tìm hiểu thêm về các điều kiện và toán tử được hỗ trợ cho các điều kiện này, hãy xem tài liệu tham khảo về biểu thức có điều kiện.

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 trước khi xuất bản (không bắt buộc), như sau:

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

Quy trình xác thực này 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 etags 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.

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

Sau khi truy xuất một mẫu và sửa đổi mẫu đó bằng các nội dung cập nhật mà bạn muốn, bạn có thể xuất bản mẫu đó. Việc phát hành mẫu như mô tả trong phần này sẽ thay thế toàn bộ mẫu cấu hình hiện có bằng tệp đã cập nhật và mẫu đang hoạt động mới được chỉ định số phiên bản lớn hơn một số so với mẫu đã thay thế.

Nếu cần, bạn có thể sử dụng API REST để quay lại phiên bản trước. Để giảm nguy cơ xảy ra lỗi trong bản cập nhật, bạn có thể xác thực trước khi phát hành.

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, đồng thời tải xuống và chỉnh sửa một mẫu, thì 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 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ị 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.

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

Sửa đổi Cấu hình từ xa bằng API REST

Phần này mô tả các chức năng chính của API REST Remote Config tại https://firebaseremoteconfig.googleapis.com. Để biết thông tin chi tiết đầy đủ, hãy xem tài liệu tham khảo API.

Nhận mã truy cập để xác thực và uỷ quyền cho các yêu cầu API

Các dự án Firebase hỗ trợ tài khoản dịch vụ của Google. Bạn có thể sử dụng tài khoản này để gọi API máy chủ Firebase từ máy chủ ứng dụng hoặc môi trường đáng tin cậy. Nếu đang phát triển mã cục bộ hoặc triển khai ứng dụng tại chỗ, bạn có thể sử dụng thông tin xác thực thu được thông qua tài khoản dịch vụ này để uỷ quyền cho các yêu cầu máy chủ.

Để xác thực tài khoản dịch vụ và uỷ quyền cho tài khoản đó truy cập vào các dịch vụ của Firebase, bạn phải tạo một tệp khoá riêng tư ở định dạng JSON.

Cách tạo tệp khoá riêng tư cho tài khoản dịch vụ:

1. Trong bảng điều khiển Firebase, hãy mở Settings (Cài đặt) > Service Accounts (Tài khoản dịch vụ).

2. Nhấp vào Tạo khoá riêng tư mới, rồi xác nhận bằng cách nhấp vào Tạo khoá.

3. Lưu trữ an toàn tệp JSON chứa khoá.

Khi uỷ quyền thông qua tài khoản dịch vụ, bạn có hai lựa chọn để cung cấp thông tin xác thực cho ứng dụng của mình. Bạn có thể đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS hoặc truyền rõ ràng đường dẫn đến khoá tài khoản dịch vụ trong mã. Bạn nên chọn phương thức đầu tiên vì phương thức này an toàn hơn.

Cách đặt biến môi trường:

Đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn tệp của tệp JSON chứa khoá tài khoản dịch vụ. Biến này chỉ áp dụng cho phiên shell hiện tại, vì vậy, nếu bạn mở một phiên mới, hãy đặt lại biến.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Sau khi bạn hoàn tất các bước trên, Thông tin xác thực mặc định của ứng dụng (ADC) có thể xác định ngầm thông tin xác thực của bạn, cho phép bạn sử dụng thông tin xác thực tài khoản dịch vụ khi kiểm thử hoặc chạy trong môi trường không phải của Google.

Sử dụng thông tin xác thực Firebase cùng với Thư viện xác thực của Google cho ngôn ngữ bạn muốn để truy xuất mã truy cập OAuth 2.0 có thời hạn ngắn:

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

public static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
FirebaseRemoteConfigSnippets.java

Sau khi mã truy cập của bạn hết hạn, phương thức làm mới mã thông báo sẽ được gọi tự động để truy xuất mã truy cập đã cập nhật.

Để uỷ quyền truy cập vào Remote Config, hãy yêu cầu phạm vi https://www.googleapis.com/auth/firebase.remoteconfig.

Sửa đổi mẫu Cấu hình từ xa

Khi làm việc với các mẫu Remote Config, hãy lưu ý rằng các mẫu này được tạo phiên bản và mỗi phiên bản có thời hạn sử dụng giới hạn từ thời điểm tạo đến thời điểm bạn thay thế phiên bản đó bằng một bản cập nhật: 90 ngày, với tổng hạn mức là 300 phiên bản được lưu trữ. Hãy xem phần Mẫu và phiên bản để biết thêm thông tin.

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

Bạn có thể sử dụng các API phụ trợ để lấy phiên bản đang hoạt động hiện tại của mẫu Remote Config ở định dạng JSON.

Các thông số và giá trị thông 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.

Sử dụng các lệnh sau:

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

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

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 trước khi xuất bản (không bắt buộc). Xác thực nội dung cập nhật mẫu bằng cách thêm tham số URL ?validate_only=true vào yêu cầu phát hành. Trong phản hồi, mã trạng thái 200 và etag đã cập nhật có hậu tố -0 có nghĩa là nội dung cập nhật của bạn đã được xác thực thành công. Mọi phản hồi không phải 200 đều cho biết dữ liệu JSON chứa lỗi mà bạn phải khắc phục trước khi phát hành.

Cập nhật mẫu Cấu hình từ xa

Sau khi truy xuất một mẫu và sửa đổi nội dung JSON bằng các nội dung cập nhật mong muốn, bạn có thể xuất bản mẫu đó. Việc phát hành mẫu như mô tả trong phần này sẽ thay thế toàn bộ mẫu cấu hình hiện có bằng tệp đã cập nhật và mẫu đang hoạt động mới được chỉ định số phiên bản lớn hơn một số so với mẫu đã thay thế.

Nếu cần, bạn có thể sử dụng API REST để quay lại phiên bản trước. Để giảm nguy cơ xảy ra lỗi trong bản cập nhật, bạn có thể xác thực trước khi phát hành.

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, đồng thời tải xuống và chỉnh sửa một mẫu, thì 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 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ị 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.

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

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

Sửa đổi các điều kiện của Cấu hình từ xa

Bạn có thể sửa đổi các điều kiện Remote Config và giá trị có điều kiện theo phương thức lập trình. Với API REST, bạn phải chỉnh sửa trực tiếp mẫu để sửa đổi các điều kiện trước khi phát hành mẫu.

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all capital letters."
    }
  }
}

Trước tiên, các nội dung sửa đổi ở trên xác định một tập hợp các điều kiện, sau đó xác định giá trị mặc định và giá trị tham số dựa trên điều kiện (giá trị có điều kiện) cho từng tham số. Tệp này cũng thêm nội dung mô tả không bắt buộc cho từng phần tử; giống như các nhận xét mã, nội dung này dành cho nhà phát triển sử dụng và không hiển thị trong ứng dụng. ETag cũng được cung cấp cho mục đích kiểm soát phiên bản.

API phụ trợ Remote Config cung cấp một số điều kiện và toán tử so sánh mà bạn có thể sử dụng để thay đổi hành vi và giao diện của ứng dụng. Để tìm hiểu thêm về các điều kiện và toán tử được hỗ trợ cho các điều kiện này, hãy xem tài liệu tham khảo về biểu thức có điều kiện.

Mã lỗi HTTP

Mã trạng thái 200 có nghĩa là mẫu Remote Config (các tham số, giá trị và điều kiện cho dự án) đã được cập nhật và hiện có sẵn cho các ứng dụng sử dụng dự án này. Các mã trạng thái khác cho biết rằng mẫu Remote Config đã tồn tại trước đó vẫn có hiệu lực.

Sau khi bạn gửi nội dung cập nhật cho mẫu, hãy chuyển đến bảng điều khiển Firebase để xác minh rằng các thay đổi của bạn xuất hiện như mong đợi. Điều này rất quan trọng vì thứ tự của các điều kiện ảnh hưởng đến cách các điều kiện đó được đánh giá (điều kiện đầu tiên đánh giá true sẽ có hiệu lực).

Việc sử dụng ETag và cập nhật bắt buộc

API REST Remote Config sử dụng thẻ thực thể (ETag) để ngăn tình trạng tương tranh và cập nhật chồng chéo cho tài nguyên. Để tìm hiểu thêm về ETag, hãy xem bài viết ETag – HTTP.

Đối với API REST, bạn nên lưu ETag do lệnh GET gần đây nhất cung cấp vào bộ nhớ đệm và sử dụng giá trị ETag đó trong tiêu đề yêu cầu If-Match khi đưa ra lệnh PUT. Nếu lệnh PUT của bạn dẫn đến Mã trạng thái HTTPS 409, bạn nên đưa ra một lệnh GET mới để lấy ETag và mẫu mới để sử dụng với lệnh PUT tiếp theo.

Bạn có thể bỏ qua ETag và tính năng bảo vệ mà ETag cung cấp bằng cách buộc cập nhật mẫu Remote Config như sau: If-Match: *Tuy nhiên, bạn không nên sử dụng phương pháp này vì có nguy cơ làm mất các bản cập nhật cho mẫu Remote Config nếu nhiều ứng dụng đang cập nhật mẫu Remote Config. Loại xung đột này có thể xảy ra với nhiều ứng dụng sử dụng API hoặc với các bản cập nhật xung đột từ ứng dụng API và người dùng bảng điều khiển Firebase.

Để biết hướng dẫn về cách quản lý các phiên bản mẫu Remote Config, hãy xem phần Mẫu Cấu hình từ xa và việc tạo phiên bản.