Riferimento API

Di seguito è riportata una panoramica delle specifiche per l'API Bundle Builder, comprese le definizioni TypeScript e le descrizioni dettagliate.

Interfaccia BundleDocument

La specifica per un singolo documento all'interno della raccolta configurata:

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

Interfaccia ParamDefinition

La specifica di un singolo parametro definito in un 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";
};

Ad esempio, dato il seguente parametro:

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

Quando si effettua una richiesta all'endpoint HTTP del bundle, il parametro può essere fornito tramite un parametro di query, ad esempio ?name=david . Il parametro può essere utilizzato all'interno di un valore QueryDefinition (vedi sotto) ( $name ) per creare dinamicamente pacchetti.

Interfaccia di definizione delle query

Una definizione di query viene utilizzata per creare query denominate nel bundle. Ogni oggetto all'interno della mappa queries creerà una nuova query denominata, utilizzando la chiave dell'oggetto come nome. Ogni query deve specificare una raccolta e, facoltativamente, un elenco di condizioni della query da eseguire.

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

Il parametro conditions può contenere una serie di interfacce QueryCondition . Ogni elemento nell'array deve includere solo una singola condizione.

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

Ad esempio, per creare una query denominata "prodotti" su una raccolta products con una condizione dove e limite, l'output della struttura dati deve corrispondere a quanto segue:

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

Quando fornisci valori di array ai filtri in , not-in o array-contains-any , devi fornire un valore separato da virgole poiché il valore come valori di array nidificati non è supportato in Firestore. Per esempio:

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

Qualsiasi valore numerico verrà analizzato come un numero, tuttavia, se è richiesto un valore numerico stringa, dovrebbe essere racchiuso tra parentesi:

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

Le condizioni possono essere utilizzate anche insieme ai parametri. Ad esempio, se viene definito un type di parametro (vedi sopra), questo può essere fornito a un valore di condizione per fornire pacchetti di dati dinamici tramite la sintassi $ :

// ?type=featured


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