Check out what’s new from Firebase at Google I/O 2022. Learn more

Sửa đổi cấu hình từ xa theo lập trình

Tài liệu này mô tả cách bạn có thể lập trình đọ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 Cấu hình Từ xa . Điều này cho phép bạn thực hiện các 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 khách.

Sử dụng API REST cấu hình từ xa hoặc SDK quản trị đượ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 để tích hợp trực tiếp các thay đổi Cấu hình từ xa vào quy trình của riêng bạn. Ví dụ: với các API phụ trợ Cấu hình từ xa, bạn có thể:

  • Lập lịch cập nhật Cấu hình từ xa . 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ị Cấu hình từ xa theo lịch trình thường xuyên.
  • Nhập hàng loạt các 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 Cấu hình từ xa Firebase.
  • Sử dụng Cấu hình từ xa với Chức năng đám mây cho Firebase , thay đổi các giá trị trong ứng dụng của bạn 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 Cấu hình từ xa để 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 quảng cáo đó sau khi bạn phát hiện đủ người đã tương tác với tính năng mới.

    Sơ đồ hiển thị phần phụ trợ Cấu hình từ xa tương tác với các công cụ và máy chủ tùy chỉnh

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 các API phụ trợ Cấu hình từ xa. Để xem lại một số mã thực hiện các tác vụ này qua API REST, hãy xem một trong các ứng dụng mẫu sau:

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

SDK quản trị 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ừ các môi trường đặc quyền. Ngoài việc thực hiện cập nhật cho Cấu hình từ xa, SDK quản trị cho phép tạo và xác minh mã thông báo xác thực Firebase, đọc và ghi từ Cơ sở dữ liệu thời gian thực, v.v. Để tìm hiểu thêm về thiết lập và điều kiện tiên quyết SDK quản trị viên, hãy xem Thêm SDK quản trị viên Firebase vào máy chủ của bạn .

Trong luồng Cấu hình từ xa điển hình, 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, sau đó xuất bản mẫu. Trước khi thực hiện các lệnh gọi API đó, bạn phải cho phép các yêu cầu từ SDK.

Khởi tạo SDK và ủy quyền các yêu cầu API

Khi bạn khởi chạy SDK quản trị không có tham số, SDK sử dụng Thông tin đăng nhập mặc định của ứng dụng Google và đọc các tùy 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ẽ được phân tích cú pháp như một đố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 tùy chọn.

Ví dụ:

Node.js

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

Java

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

Lấy mẫu cấu hình từ xa hiện tại

Khi làm việc với các mẫu Cấu hình từ xa, hãy nhớ rằng chúng được tạo phiên bản và mỗi phiên bản có thời gian tồn tại giới hạn từ thời điểm tạo cho đến khi bạn thay thế bằng bản cập nhật: 90 ngày, với tổng giới hạn là 300 phiên bản được lưu trữ. Xem 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ợ để tải phiên bản hoạt động hiện tại của mẫu Cấu hình từ xa ở định dạng JSON. Để lấy mẫu:

Node.js

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

Java

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ể lập trình sửa đổi và thêm các tham số và nhóm tham số Cấu hình từ xa. Ví dụ: đối với một nhóm tham số hiện có có tên "new_menu", bạn có thể thêm một tham số để kiểm soát việc hiển thị thông tin theo mùa:

Node.js

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

Java

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 các giá trị mặc định, giá trị điều kiện và 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 khi thực hiện các sửa đổi.

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

Bạn có thể lập trình sửa đổi và thêm các điều kiện Cấu hình từ xa và các giá trị điều kiện. Ví dụ, để thêm một điều kiện mới:

Node.js

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

Java

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 khi thực hiện các sửa đổi.

Các API phụ trợ Cấu hình từ xa 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 ứng dụng của mình. Để 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 điều kiện .

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

Theo tùy chọn, bạn có thể xác thực các bản cập nhật của mình trước khi xuất bản, như được hiển thị:

Node.js

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

Java

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

Quá trình xác thực này kiểm tra các lỗi như các khóa 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 các thẻ etag bị định dạng sai. Ví dụ: một yêu cầu chứa nhiều hơn số lượng khóa cho phép — 2000 — sẽ trả về thông báo lỗi, số lượng tham 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 nó với các bản cập nhật mong muốn của bạn, sau đó bạn có thể xuất bản nó. Việc xuất bản một mẫu như được 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 hiện hoạt mới được gán một số phiên bản lớn hơn một số so với mẫu mà nó đã thay thế.

Nếu cần, bạn có thể sử dụng API REST để quay trở lại phiên bản trước . Để giảm thiểu rủi ro lỗi trong bản cập nhật, bạn có thể xác thực trước khi xuất bản .

Node.js

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

Java

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 khả năng chính của API REST cấu hình từ xa tại https://firebaseremoteconfig.googleapis.com . Để biết chi tiết đầy đủ, hãy xem tài liệu tham khảo API .

Nhận mã thông báo truy cập để xác thực và cho phép 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 các API máy chủ Firebase từ máy chủ ứng dụng hoặc môi trường đáng tin cậy của mình. Nếu bạn đang phát triển mã cục bộ hoặc triển khai ứng dụng của mình tại chỗ, bạn có thể sử dụng thông tin đăng nhập có được qua tài khoản dịch vụ này để cho phép các yêu cầu của máy chủ.

Để xác thực tài khoản dịch vụ và cho phép tài khoản đó truy cập các dịch vụ Firebase, bạn phải tạo tệp khóa cá nhân ở định dạng JSON.

Để tạo tệp khóa riêng tư cho tài khoản dịch vụ của bạn:

  1. Trong bảng điều khiển Firebase, mở Cài đặt> Tài khoản dịch vụ .

  2. Nhấp vào Tạo khóa riêng tư mới , sau đó xác nhận bằng cách nhấp vào Tạo khóa .

  3. Lưu trữ an toàn tệp JSON có chứa khóa.

Khi ủy quyền qua tài khoản dịch vụ, bạn có hai lựa chọn để cung cấp thông tin đăng nhập của mình. Bạn có thể đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS hoặc bạn có thể chuyển rõ ràng đường dẫn đến khóa tài khoản dịch vụ trong mã. Tùy chọn đầu tiên là an toàn hơn và được khuyến khí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 có chứa khóa tài khoản dịch vụ của bạn. 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.

Linux hoặc macOS

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

các cửa sổ

Với PowerShell:

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

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

Sử dụng thông tin đăng nhập Firebase của bạn cùng với Thư viện Google Auth cho ngôn ngữ ưa thích của bạn để truy xuất mã thông báo truy cập OAuth 2.0 tồn tại trong thời gian ngắn:

node.js

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

Trong ví dụ này, thư viện ứng dụng Google API xác thực yêu cầu bằng mã thông báo web JSON hoặc JWT. Để biết thêm thông tin, hãy xem mã thông báo web JSON .

Python

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

Java

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

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

Để cấp quyền truy cập vào Cấu hình từ xa, 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 Cấu hình từ xa, hãy nhớ rằng chúng được tạo phiên bản và mỗi phiên bản có thời gian tồn tại giới hạn từ thời điểm tạo cho đến khi bạn thay thế bằng bản cập nhật: 90 ngày, với tổng giới hạn là 300 phiên bản được lưu trữ. Xem Mẫu và Phiên bản để biết thêm thông tin.

Lấy mẫu cấu hình từ xa hiện tại

Bạn có thể sử dụng các API phụ trợ để tải phiên bản hoạt động hiện tại của mẫu Cấu hình từ xa ở định dạng JSON. Sử dụng các lệnh sau:

Xoăn

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

Lệnh này xuất tải trọng JSON vào một tệp và các tiêu đề (bao gồm Etag) vào một tệp riêng biệt.

Yêu cầu HTTP thô

Host: firebaseremoteconfig.googleapis.com

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

Lệnh gọi API này trả về JSON sau, cùng với tiêu đề riêng biệt bao gồm thẻ ETag mà bạn sử dụng cho yêu cầu tiếp theo.

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

Theo tùy chọn, bạn có thể xác thực các bản cập nhật của mình trước khi xuất bản. Xác thực các bản cập nhật mẫu bằng cách thêm vào yêu cầu xuất bản của bạn tham số URL ?validate_only=true . Trong phản hồi, mã trạng thái 200 và etag được cập nhật với 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. Bất kỳ phản hồi nào không phải 200 đều chỉ ra rằng dữ liệu JSON chứa các lỗi mà bạn phải sửa trước khi 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 với các bản cập nhật mong muốn của bạn, sau đó bạn có thể xuất bản nó. Việc xuất bản một mẫu như được 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 hiện hoạt mới được gán một số phiên bản lớn hơn một số so với mẫu mà nó đã thay thế.

Nếu cần, bạn có thể sử dụng API REST để quay trở lại phiên bản trước . Để giảm thiểu rủi ro lỗi trong bản cập nhật, bạn có thể xác thực trước khi xuất bản .

Xoăn

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

Đối với lệnh curl này, bạn có thể chỉ định nội dung bằng cách sử dụng ký tự "@", theo sau là tên tệp.

Yêu cầu HTTP thô

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

Bởi vì đây là một yêu cầu ghi, ETag được sửa đổi bởi lệnh này và một ETag cập nhật được cung cấp trong tiêu đề phản hồi của lệnh PUT tiếp theo.

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

Bạn có thể lập trình sửa đổi các điều kiện Cấu hình từ xa và các giá trị có điều kiện. Với REST API, bạn phải chỉnh sửa mẫu trực tiếp để sửa đổi các điều kiện trước khi xuất bản 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."
    }
  }
}

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

Các API phụ trợ Cấu hình từ xa 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 ứng dụng của mình. Để 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 điều kiện .

Mã lỗi HTTP

Mã trạng thái Nghĩa
200 Cập nhật thành công
400 Đã xảy ra lỗi xác thực. Ví dụ: một yêu cầu chứa nhiều hơn số khóa cho phép — 2000 — sẽ trả về 400 (Yêu cầu không hợp lệ) kèm theo thông báo lỗi, số lượng tham Param count too large . Ngoài ra, Mã trạng thái HTTPS này có thể xảy ra trong hai trường hợp sau:
  • Đã xảy ra lỗi phiên bản không khớp do tập hợp giá trị và điều kiện đã được cập nhật kể từ lần cuối bạn truy xuất giá trị ETag. Để giải quyết vấn đề này, bạn nên sử dụng lệnh GET để nhận mẫu mới và giá trị ETag, cập nhật mẫu, sau đó gửi bằng cách sử dụng mẫu đó và giá trị ETag mới.
  • Lệnh PUT (Cập nhật yêu cầu mẫu cấu hình từ xa) đã được thực hiện mà không chỉ định tiêu đề If-Match .
401 Đã xảy ra lỗi ủy quyền (không có mã thông báo truy cập nào được cung cấp hoặc API REST cấu hình từ xa của Firebase chưa được thêm vào dự án của bạn trong Bảng điều khiển dành cho nhà phát triển đám mây)
403 Đã xảy ra lỗi xác thực (cung cấp sai mã thông báo truy cập)
500 Đã xảy ra lỗi nội bộ. Nếu lỗi này xảy ra, hãy gửi yêu cầu hỗ trợ của Firebase

Mã trạng thái 200 có nghĩa là mẫu Cấu hình từ xa (thông 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 Cấu hình từ xa đã tồn tại trước đó vẫn còn hiệu lực.

Sau khi bạn gửi các bản cập nhật cho mẫu của mình, hãy truy cập 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 chúng được đánh giá (điều kiện đầu tiên đánh giá true có hiệu lực).

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

API REST cấu hình từ xa sử dụng thẻ thực thể (ETag) để ngăn chặn các điều kiện cuộc đua 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 ETag - HTTP .

Đối với API REST, Google khuyên bạn nên lưu vào bộ nhớ cache ETag được cung cấp bởi lệnh GET gần đây nhất và sử dụng giá trị ETag đó trong tiêu đề yêu cầu If-Match khi phát 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 ra lệnh GET mới để lấy ETag và mẫu mới để sử dụng với lệnh PUT tiếp theo của bạn.

Bạn có thể phá vỡ ETag và bảo vệ mà nó cung cấp, bằng cách buộc cập nhật mẫu Cấu hình từ xa như sau: If-Match: * Tuy nhiên, cách tiếp cận này không được khuyến nghị vì nó có nguy cơ làm mất các bản cập nhật cho Cấu hình từ xa của bạn nếu nhiều máy khách đang cập nhật mẫu Cấu hình từ xa. Loại xung đột này có thể xảy ra với nhiều ứng dụng khách sử dụng API hoặc với các bản cập nhật xung đột từ ứng dụng khách 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 Cấu hình từ xa, hãy xem các mẫu và lập phiên bản Cấu hình từ xa .