Skip to content

Latest commit

 

History

History
339 lines (277 loc) · 13.6 KB

README.fr.md

File metadata and controls

339 lines (277 loc) · 13.6 KB
Raw

Onfleet Node.js Wrapper

Build License Latest version Top language Dependencies Downloads

Lisez ce document dans une autre langue:
English
正體中文
Español

Visitez notre article de blog sur le projet de wrapper API pour en savoir plus sur nos initiatives.
Si vous avez des questions, veuillez contacter Onfleet en soumettant un problème ici ou contactez support@onfleet.com.

Table des matières

Synopsis

La bibliothèque Onfleet Node.js offre un accès pratique à l'API Onfleet.

Installation

npm install @onfleet/node-onfleet

Pour TypeScript, installez la typed definition:

npm install @types/onfleet__node-onfleet

Bravo à @marcobeltempo pour la contribution!

Utilisation

Avant d'utiliser le wrapper de l'API, vous devez vous procurer une clé API auprès de votre administrateur d'organisation.

La création et l'intégration des clés API sont effectuées via le tableau de bord Onfleet.

Pour commencer à utiliser l'API Onfleet, il vous suffit de créer un objet Onfleet avec votre clé API:

const onfleetApi = new Onfleet("<your_api_key>");

En tant que champ facultatif, vous pouvez introduire un délai d'expiration personnalisé inférieur à la valeur par défaut de 70000 ms (délai d'expiration de l'API Onfleet par défaut) en fournissant un 2ème paramètre:

const onfleetApi = new Onfleet("<your_api_key>", 30000);

En tant que champ facultatif, vous pouvez introduire un objet d'options pour Bottleneck.

const onfleetApi = new Onfleet("<your_api_key>", 30000, {
  LIMITER_RESERVOIR: 10,               // Default: 20
  LIMITER_WAIT_UPON_DEPLETION: 20000,  // Default: 10000
  LIMITER_MAX_CONCURRENT: 5,           // Default: 1
  LIMITER_MIN_TIME: 50,                // Default: 50
});

Authentification

Une fois que l'objet Onfleet est créé, vous pouvez tester le noeud final d'authentification:

onfleet.verifyKey();  // Returns a boolean

Une fois que l'objet Onfleet est créé, vous aurez accès à tous les points de terminaison de l'API, comme indiqué dans la Documentation de l'API Onfleet. Voici quelques cas d'utilisation:

Tests unitaires

npm test

Tests unitaires à l'aide de Docker

docker-compose up --build

Étranglement

La limitation de débit est appliquée par l'API avec un seuil de 20 demandes par seconde pour toutes les clés d'API de votre organisation. Pour en savoir plus, cliquez ici.

Nous avons mis en place un limiteur sur le wrapper lui-même pour vous éviter de dépasser involontairement vos limitations de taux et éventuellement être banni.

Réponses

La bibliothèque renvoie le body d'un objet Response.

Opérations CRUD prises en charge

Voici les opérations CRUD prises en charge pour chaque ordinateur d'extrémité:

Entity GET POST PUT DELETE
Admins/Administrators get() create(obj)
matchMetadata(obj)		 update(id, obj) deleteOne(id)
Containers get(id, 'workers')
get(id, 'teams')
get(id, 'organizations')		 x insertTask(id, obj) x
Destinations get(id) create(obj)
matchMetadata(obj)		 x x
Hubs get() create(obj) update(id, obj) x
Organization get()
get(id)		 x x x
Recipients get(id)
get(name, 'name')
get(phone, 'phone')		 create(obj)
matchMetadata(obj)		 update(id, obj) x
Tasks get(query)
get(id)
get(shortId, 'shortId')		 create(obj)
clone(id)
clone(id, obj)
forceComplete(id, obj)
batchCreate(obj)
batchCreateAsync(obj)
getBatch(id)
autoAssign(obj)
matchMetadata(obj)		 update(id, obj) deleteOne(id)
Teams get()
get(id)
getWorkerEta(id, obj)
getTasks(id)		 create(obj)
autoDispatch(id, obj)		 update(id, obj) deleteOne(id)
Webhooks get() create(obj) x deleteOne(id)
Workers get()
get(query)
get(id)
getByLocation(obj)
getSchedule(id)
getTasks(id)		 create(obj)
setSchedule(id, obj)
matchMetadata(obj)
getDeliveryManifest(obj)		 update(id, obj)
insertTask(id, obj)		 deleteOne(id)

Demandes GET

Pour obtenir tous les documents d'un noeud final, cela renvoie une Promise contenant un tableau de résultats:

get();
Exemples de get()
onfleetApi.workers.get().then((results) => { /* ... */ });
onfleetApi.workers.get({ queryParams }).then((results) => { /* ... */ });

Option permettant d'utiliser des paramètres de requête pour certains points de terminaison, reportez-vous aux documents de l'API pour les points de terminaison prenant en charge les paramètres de requête.

onfleetApi.workers.get({ phones: "<phone_number>" }).then((results) => { /* ... */ });

onfleetApi.tasks.get({ from: "<from_time>", to: "<to_time>" }).then((results) => { /* ... */ });

Les paramètres de requête peuvent figurer dans n’importe quel formulaire, à condition qu’il s’agisse d’un objet JSON, par exemple: { analytics: true } et { 'analytics': 'true' } sont identiques

Pour obtenir l'un des documents dans un noeud final, si paramName facultatif n'est pas fourni, l'encapsuleur effectuera une recherche par ID. Si paramName est fourni, il recherchera par paramName:

get(<parameter>, <paramName> (optional), <queryParam> (optional));

Options pour paramName:

  • id
  • name
  • phone
  • shortId
Exemples de get(param)
onfleetApi.workers.get("<24_digit_ID>").then((result) => { /* ... */ });
onfleetApi.workers.get("<24_digit_ID>", { analytics: true }).then((result) => { /* ... */ });

onfleetApi.tasks.get("<shortId>", "shortId").then((result) => { /* ... */ });

onfleetApi.recipients.get("<phone_number>", "phone").then((result) => { /* ... */ });
onfleetApi.recipients.get("<recipient_name>", "name").then((result) => { /* ... */ });
onfleetApi.recipients
  .get("<recipient_name>", "name", { skipPhoneNumberValidation: true })
  .then((result) => { /* ... */ });

onfleetApi.containers.get("<24_digit_ID>", "workers").then((result) => { /* ... */ });
onfleetApi.containers.get("<24_digit_ID>", "teams").then((result) => {{ /* ... */ });
onfleetApi.containers.get("<24_digit_ID>", "organizations").then((result) => { /* ... */ });

Pour obtenir des informations sur un lot spécifique

Exemples de getBatch(id)
onfleetAPI.tasks.getBatch("<jobId>","jobId").then((result) => { /* ... */ });

Pour obtenir un pilote par emplacement, utilisez la fonction getByLocation:

getByLocation({ queryParams });
Exemples de getByLocation
const locationParams = {
  longitude: -122.404,
  latitude: 37.789,
  radius: 10000,
};

onfleetApi.workers.getByLocation(locationParams).then((results) => { /* ... */ });

Demandes POST

Pour créer un document dans un noeud final:

create({ data });
Exemples de create()
const data = {
  name: "John Driver",
  phone: "+16173428853",
  teams: ["<team_ID>", "<team_ID> (optional)", ...],
  vehicle: {
    type: "CAR",
    description: "Tesla Model 3",
    licensePlate: "FKNS9A",
    color: "purple",
  },
};

onfleetApi.workers.create(data);
Exemples de getDeliveryManifest()
const data = {
  hubId: "<hubId>", // Required
  workerId: "<workerId", // Required
  googleApiKey: "<google_direction_api_key>", // Optional
  startDate: "<startDate>", // Optional
  endDate: "<endDate>" // Optional
};

onfleetApi.workers.getDeliveryManifest(data);

Les requêtes POST étendues incluent clone, forceComplete, batchCreate,batchCreateAsync, autoAssign, setSchedule, autoDispatch:

onfleetApi.tasks.clone('<24_digit_ID>');
onfleetApi.tasks.forceComplete('<24_digit_ID>', { data });
onfleetApi.tasks.batchCreate({ data });
onfleetApi.tasks.batchCreateAsync({ data });
onfleetApi.tasks.autoAssign({ data });

onfleetApi.workers.setSchedule('<24_digit_ID>', { data });
onfleetAPI.workers.getDeliveryManifest({ data });

onfleetApi.teams.autoDispatch('<24_digit_ID>', { data });

onfleetApi.<entity_name_pluralized>.matchMetadata({ data });

Pour plus de détails, consultez notre documentation sur clone, forceComplete, batchCreate, autoAssign, setSchedule, getDeliveryManifest, matchMetadata, et autoDispatch.

Demandes PUT

Pour mettre à jour un document dans un noeud final:

update("<24_digit_ID>", { data });
Exemples de update()
const newData = {
  name: "Jack Driver",
};

onfleetApi.workers.update("<24_digit_ID>", newData);
Exemples de insertTask()
onfleetApi.workers.insertTask("<24_digit_ID>", { data }).then((result) => { /* ... */ });

Demandes DELETE

Pour supprimer un document dans un noeud final:

deleteOne("<24_digit_ID>");
Exemples de deleteOne()
onfleetApi.workers.deleteOne("<24_digit_ID>");

Exemples d'utilisation de vos opérations CRUD

  • Obtenez tous les destinataires:

    onfleetApi.tasks
  .get({ from: "1557936000000", to: "1558022400000" })
  .then((tasks) => {
    for (let task of tasks) {
      if (task.recipients[0] !== undefined) {
        // Do something with the recipients
      }
    }
  })
  .catch((err) => { /* ... */ });

  • async/await peut également être utilisé dans les cas suivants:

    async function findAllWorkers() {
  try {
    let response = await onfleetApi.workers.get();
    // Do something with the response
  }
  catch (err) { /* ... */ }
}

findAllWorkers();

Choses à ne pas faire

  • Modèle inefficace, utilisez plutôt des métadonnées: 
    // DONT
onfleetApi.workers
  .get()
  .then((workers) => {
    for (let worker of workers) {
      for (let metadataEntry of worker.metadata) {
        if (metadataEntry.name === "hasFreezer" && metadataEntry.value) {
          // Do something
        }
      }
    }
  })
  .catch((err) => { /* ... */ });

// DO
onfleetApi.workers
  .matchMetadata([{"name": "hasFreezer", "type": "boolean", "value": true}])
  .then((workers) => {
    for (let worker of workers) {
      // Do something
    }
  })
  .catch((err) => { /* ... */ });

Haut de page.