مرجع 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 Interface

مشخصات یک پارامتر واحد تعریف‌شده در 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) (در زیر ببینید) برای ایجاد پویای دسته‌ها استفاده کرد.

میانای QueryDefinition

از تعریف پُرسمان برای ایجاد پُرسمان‌های نام‌گذاری‌شده در بسته استفاده می‌شود. هر شیء در نقشه 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 با شرط 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'] },