مرجع 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 بسته، پارامتر را می توان از طریق یک پارامتر query ارائه کرد، به عنوان مثال ?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" در مجموعه 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'] },