مرجع واجهة برمجة تطبيقات

يحتوي أدناه على نظرة عامة على مواصفات Bundle Builder API، بما في ذلك تعريفات TypeScript والأوصاف التفصيلية.

واجهة حزمة المستندات

مواصفات مستند واحد ضمن المجموعة المكونة:

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

واجهة تعريف المعلمة

مواصفات معلمة واحدة محددة في 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 ) لإنشاء الحزم ديناميكيًا.

واجهة تعريف الاستعلام

يتم استخدام تعريف الاستعلام لإنشاء استعلامات مسماة على الحزمة. سيقوم كل كائن داخل خريطة 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 بشرط المكان والحد، يجب أن يتطابق مخرجات بنية البيانات مع ما يلي:

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'] },