הפניית API

בהמשך מופיעה סקירה כללית של המפרטים של Bundle Builder API, כולל הגדרות TypeScript ותיאורים מפורטים.

ממשק BundleDocument

המפרט של מסמך יחיד בתוך הקולקציה שהוגדרה:

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

ממשק ParamDefinition

המפרט של פרמטר יחיד שמוגדר ב-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";
};

לדוגמה, בהינתן הפרמטר הבא:

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

כששולחים בקשה לנקודת הקצה של ה-HTTP של החבילה, אפשר לספק את הפרמטר באמצעות פרמטר שאילתה, למשל ?name=david. אפשר להשתמש בפרמטר בתוך ערך QueryDefinition (ראו בהמשך) ($name) כדי ליצור חבילות באופן דינמי.

ממשק QuerySetup

הגדרת שאילתות משמשת ליצירת שאילתות בעלות שם בחבילה. כל אובייקט במפה queries ייצור שאילתה חדשה בעלת שם, שמפתח האובייקט ישמש כשם שלה. בכל שאילתה צריך לציין אוסף, ואפשר גם לציין רשימה של תנאי שאילתה לביצוע.

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

הפרמטר conditions יכול להכיל מערך של ממשקים מסוג QueryCondition. כל פריט במערך חייב לכלול רק תנאי אחד.

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

לדוגמה, כדי ליצור שאילתה בשם 'products' באוסף products עם תנאי where ו-limit, הפלט של מבנה הנתונים צריך להתאים לקוד הבא:

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

כשמציינים ערכים של מערך למסננים in, ‏ not-in או array-contains-any, צריך לציין ערך שמופרד בפסיקים, כי אין תמיכה בערכים של מערך בתוך מערך ב-Firestore. לדוגמה:

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

כל ערך מספרי יפורש כמספר, אבל אם נדרש ערך מספרי של מחרוזת, צריך להקיף אותו בסוגריים:

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

אפשר להשתמש בתנאים גם לצד פרמטרים. לדוגמה, אם מוגדר פרמטר type (ראו למעלה), אפשר להוסיף אותו לערך תנאי כדי לספק חבילות נתונים דינמיות באמצעות התחביר $:

// ?type=featured


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