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 theo phương thức lập trình và sửa đổi tập hợp các thông số và điều kiện theo định dạng JSON được gọi là Mẫu Remote Config. Điều này cho phép thay đổi mẫu trên phần phụ trợ mà ứng dụng khách có thể tìm nạp bằng thư viện ứng dụng.

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 Remote Config API phụ trợ, bạn có thể:

• Lên lịch cập nhật Remote Config. Bằng cách sử dụng các lệnh gọi API cùng với một công việc định kỳ, bạn có thể thay đổi các giá trị Remote Config theo lịch thường xuyên.
• 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 cáo một tính năng mới trong ứng dụng của mình, sau đó tự động tắt chương trình khuyến mãi đó khi bạn phát hiện đã có đủ số 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 Java Cấu hình từ xa Firebase API REST
• 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ị của Firebase

Admin SDK là một tập hợp các thư viện máy chủ cho phép bạn tương tác với Firebase từ môi trường đặc quyền. Ngoài việc cập nhật vào Remote Config, Admin SDK 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 chạy Admin SDK mà không có tham số, SDK sẽ sử dụng Thông tin đăng nhập mặc định của ứng dụng trên Google và đọc các lựa 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ó sẽ là đượ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 một 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 "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 xuất bản mẫu một cách rõ ràng sau thực hiện sửa đổi.

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 xuất bản mẫu một cách rõ ràng sau thực hiện sửa đổi.

API phụ trợ Remote Config cung cấp một số điều kiện và thông tin 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. Người nhận hãy 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 tham chiếu biểu thức có điều kiện.

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

Nếu muốn, bạn có thể xác thực nội dung cập nhật trước khi xuất bản, như minh hoạ dưới đây:

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 lỗi, chẳng hạn 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 thẻ điện tử bị định dạng sai. Ví dụ: một yêu cầu chứa nhiều khoá hơn số 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 đó. Xuất bản mẫu như được mô tả trong phần này thay thế toàn bộ mẫu cấu hình hiện có bằng tệp được cập nhật và mẫu hoạt động mới được gán số phiên bản một số lớn hơn mẫu mà nó thay thế.

Nếu cần, bạn có thể sử dụng API REST để khôi phục về 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à nội dung 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 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 ứng dụng chứa điều kiện dựa vào một mã ứng dụng hoặc người dùng cụ thể đối tượ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 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 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 qua tài khoản dịch vụ, bạn có hai lựa chọn để cung cấp vào ứng dụng của bạn. Bạn có thể đặt GOOGLE_APPLICATION_CREDENTIALS biến môi trường, hoặc bạn có thể chuyển đường dẫn đến khoá tài khoản dịch vụ trong mã một cách rõ ràng. 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 của bạn, 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 dịch vụ thông tin đăng nhập tài khoản khi thử nghiệm hoặc chạy trong các 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 cụ thể dưới dạng biến thể trong một A/B Testing thử nghiệm không được bao gồm trong các 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

Nếu muốn, bạn có thể xác thực nội dung cập nhật trước khi xuất bản. 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à một thẻ etag đã cập nhật có hậu tố -0 có nghĩa là bản cập nhật của bạn đã được xác thực thành công. Mọi câu trả lời không phải 200 cho biết dữ liệu JSON chứa các lỗi mà bạn phải sửa trước xuất bản.

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

Sau khi truy xuất mẫu và sửa đổi nội dung JSON theo ý bạn bản cập nhật ứng dụng, sau đó bạn có thể xuất bản bản cập nhật đó. 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 để khôi phục về phiên bản trước đó. Để giảm thiểu rủi ro xảy ra lỗi trong một bản cập nhật, bạn có thể xác thực trước khi xuất bản.

Các điều kiện và nội dung 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 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 ứng dụng chứa điều kiện dựa vào một mã ứng dụng hoặc người dùng cụ thể đối tượ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 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ể lập trình để sửa đổi Remote Config điều kiện và điều kiện giá trị. 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à thông tin 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. Người nhận hãy 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 tham chiếu 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 Remote Config mẫu đã 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ác điều kiện sẽ ảnh hưởng đến cách đánh giá chúng (điều kiện đầu tiên mà đánh giá true có hiệu lực).

Mức sử dụng ETag và bản cập nhật bắt buộc

API REST Remote Config sử dụng một thẻ thực thể (ETag) để ngăn chặn các tình huống tương tranh và chồng chéo cập nhật vào tài nguyên. Để tìm hiểu thêm về ETag, hãy xem 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 PUT của bạn dẫn đến Mã trạng thái HTTPS 409, bạn nên phát hành một GET mới để có được một 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.