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

في ما يلي نظرة عامة على مواصفات واجهة برمجة التطبيقات 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) لإنشاء حِزم ديناميكيًا.

واجهة 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'] },