Tài liệu tham khảo API

Dưới đây là thông tin tổng quan về các quy cách của Bundle Builder API, bao gồm cả các định nghĩa TypeScript và nội dung mô tả chi tiết.

Giao diện BundleDocument

Quy cách cho một tài liệu trong bộ sưu tập đã định cấu hình:

type BundleDocument = {
  // A list of document IDs to serve in the bundle.
  docs?: Array<string>;
  // A map containing individual named queries and their definitions.
  queries?: Map<string, QueryDefinition[]>;
  // A map of parameters and their definitions, which can be provided to a query definition.
  params?: Map<string, ParamDefinition>;
  // Specifies how long to keep the bundle in the client's cache, in seconds. If not defined, client-side cache is disabled.
  clientCache?: string;
  // Only used in combination with Firebase Hosting. Specifies how long to keep the bundle in Firebase Hosting CDN cache, in seconds.
  serverCache: string;
  // Specifies how long (in seconds) to keep the bundle in a Cloud Storage bucket, in seconds. If not defined, Cloud Storage bucket is not accessed.
  fileCache?: string;
  // If a 'File Cache' is specified, bundles created before this timestamp will not be file cached.
  notBefore?: Timestamp;
};

Giao diện ParamDefinition

Quy cách của một tham số duy nhất được xác định trong BundleDocument.

type ParamDefinition = {
  // Whether this parameter is required. If not provided as a query string, an error will be thrown.
  required: boolean;
  // The type of value which will be parsed, defaults to 'string'.
  type?:
    | "string"
    | "integer"
    | "float"
    | "boolean"
    | "string-array"
    | "integer-array"
    | "float-array";
};

Ví dụ: với tham số sau:

params: {
  name: {
    required: true,
    type: 'string',
  }
}

Khi đưa ra yêu cầu đối với điểm cuối HTTP của gói, bạn có thể cung cấp tham số thông qua tham số truy vấn, ví dụ: ?name=david. Bạn có thể dùng tham số này trong giá trị QueryDefinition (xem bên dưới) ($name) để tạo các gói một cách linh hoạt.

Giao diện QueryDefinition

Định nghĩa truy vấn được dùng để tạo các truy vấn có tên trên gói. Mỗi đối tượng trong bản đồ queries sẽ tạo một truy vấn có tên mới, sử dụng khoá đối tượng làm tên. Mỗi truy vấn phải chỉ định một tập hợp và có thể là một danh sách các điều kiện truy vấn để thực hiện.

type QueryDefinition = {
  // The collection to perform the query on.
  collection: string;
  // An optional list of conditions to perform on the specified collection.
  conditions?: QueryCondition[];
};

Tham số conditions có thể chứa một mảng các giao diện QueryCondition. Mỗi mục trong mảng chỉ được chứa một điều kiện.

type QueryCondition = {
  // Performs a `where` filter on the collection on a given FieldPath, operator and value.
  where?: [
    string,
    (
      | "<"
      | "<="
      | "=="
      | ">="
      | ">"
      | "!="
      | "array-contains"
      | "in"
      | "not-in"
      | "array-contains-any"
    ),
    any
  ];
  orderBy?: [string, ("asc" | "desc")?];
  limit?: number;
  limitToLast?: number;
  offset?: number;
  startAt?: string;
  startAfter?: string;
  endAt?: string;
  endBefore?: string;
};

Ví dụ: để tạo một truy vấn có tên "products" trên một tập hợp products có điều kiện where và limit, đầu ra cấu trúc dữ liệu phải khớp với nội dung sau:

queries: {
  products: {
    collection: 'products',
    conditions: [
      { where: ['type', '==', 'featured'] },
      { limit: 10 },
    ],
  }
}

Khi cung cấp các giá trị mảng cho bộ lọc in, not-in hoặc array-contains-any, bạn phải cung cấp một giá trị được phân tách bằng dấu phẩy làm giá trị vì Firestore không hỗ trợ các giá trị mảng lồng nhau. Ví dụ:

{ where: ['category', 'in', 'womens,shorts'] }, // ['womens', 'shorts']

Mọi giá trị số sẽ được phân tích cú pháp dưới dạng số, tuy nhiên, nếu cần giá trị số dạng chuỗi, bạn nên đặt giá trị đó trong dấu ngoặc đơn:

{ where: ['price', 'in', '1,2.5'] }, // [1, 2.5]
{ where: ['price', 'in', '"1","2.5"'] }, // ['1', '2.5']

Bạn cũng có thể sử dụng các điều kiện cùng với các tham số. Ví dụ: nếu một tham số type được xác định (xem ở trên), thì tham số này có thể được cung cấp cho một giá trị điều kiện để cung cấp các gói dữ liệu động thông qua cú pháp $:

// ?type=featured


    conditions: [
      { where: ['type', '==', '$type'] },