README

用其他语言阅读此文档: 西班牙语

访问我们关于 API 包装项目 的博客文章，了解更多关于我们的举措。如果您有任何问题，请通过提交问题 此处 或联系 support@onfleet.com 联系我们。

目录

• 目录
• 概述
• 安装
• 需求
• 使用
  • 身份验证
  • 限流
  • 支持的 CRUD 操作
    • GET 请求
      • get() 的示例
      • get(param) 的示例
      • getByLocation 的示例
    • POST 请求
      • create() 的示例
    • PUT 请求
      • update() 的示例
      • insertTask() 的示例
    • DELETE 请求
      • deleteOne() 的示例
  • 使用 CRUD 操作的示例
  • 不要做的事情

概述

Onfleet PHP 库提供了对 Onfleet API 的便捷访问。

安装

composer require onfleet/php-onfleet

需求

Onfleet PHP 库需要安装 bcmath 扩展 （链接）。

使用

在开始使用 API 包装器之前，您需要从您的组织管理员那里获取 API 密钥。

API 密钥的创建和集成通过 Onfleet 仪表板 进行。

要开始使用库，您只需使用您的 API 密钥创建一个 Onfleet 对象

$onfleet = new Onfleet("<your_api_key>");

可选地，您可以通过提供一个第二个参数来引入一个自定义的超时时间，该时间小于默认的 Onfleet API 超时（70,000 毫秒）

$onfleet = new Onfleet("<your_api_key>", 30000);

身份验证

一旦创建 Onfleet 对象，您就可以在身份验证端点进行测试

$onfleet->verifyKey();  // Returns a boolean

限流

API 对请求速率进行限制，所有组织 API 密钥的阈值为每秒 20 个请求。更多详情 （链接）。

我们还实现了此库的限制器，以避免您无意中超过速率限制，并最终被禁止。

支持的 CRUD 操作

以下是每个实体可用的操作

GET 请求

要获取端点内的所有文档，此操作返回一个结果数组

get();

get() 的示例

$onfleet->workers->get();
$onfleet->workers->get($queryParams);

可选地，您可以发送一个查询参数数组，用于某些端点。有关支持查询参数的端点，请参阅 API 文档。

$onfleet->workers->get([ "phones" => "<phone_number>" ]);

$onfleet->tasks->get([ "from" => "<from_time>", "to" => "<to_time>" ]);

要获取端点内的单个文档，如果未提供可选的 paramName，则库将按 ID 搜索。如果提供了 paramName，则按 paramName 搜索

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

paramName 可以是以下任何一项

• id
• name
• phone
• shortId

get(param) 的示例

$onfleet->workers->get("<24_digit_ID>");
$onfleet->workers->get("<24_digit_ID>", [ "analytics" => true ]);

$onfleet->tasks->get("<shortId>", "shortId");

$onfleet->recipients->get("<phone_number>", "phone");
$onfleet->recipients->get("<recipient_name>", "name");
$onfleet->recipients->get("<recipient_name>", "name", [ "skipPhoneNumberValidation" => true ]);


$onfleet->containers->get("<24_digit_ID>", "workers");
$onfleet->containers->get("<24_digit_ID>", "teams");
$onfleet->containers->get("<24_digit_ID>", "organizations");

要通过位置获取司机，请使用 getByLocation 函数

getByLocation($queryParams);

getByLocation 的示例

$locationParams = [
  "longitude" => -122.404,
  "latitude" => 37.789,
  "radius" => 10000,
];

$onfleet->workers->getByLocation($locationParams);

POST 请求

要在端点内创建文档

create($data);

create() 的示例

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

$onfleet->workers->create($data);

getDeliveryManifest() 的示例

$data = [
  "hubId" => "<hubId>", // Required
  "workerId" => "<workerId>", // Required
  "googleApiKey" => "<googleApiKey>", // Optional
  "startDate" => "<startDate>", // Optional - Timestamp format e.g. 1557936000000
  "endDate" => "<endDate>" // Optional - Timestamp format e.g. 1557936000000
];

$onfleet->workers->getDeliveryManifest($data);

扩展的 POST 请求包括 Tasks 端点的 clone、forceComplete、batchCreate、autoAssign；Workers 端点的 setSchedule；Teams 端点的 autoDispatch；以及所有受支持实体的 matchMetadata。例如

$onfleet->tasks->clone('<24_digit_ID>');
$onfleet->tasks->forceComplete('<24_digit_ID>', $data);
$onfleet->tasks->batchCreate($data);
$onfleet->tasks->autoAssign($data);

$onfleet->workers->setSchedule('<24_digit_ID>', $data);
$onfleet->workers->getDeliveryManifest($data);

$onfleet->teams->autoDispatch('<24_digit_ID>', $data);

$onfleet-><entity_name_pluralized>->matchMetadata($data);

有关更多详细信息，请查看我们关于 clone、forceComplete、batchCreate、autoAssign、setSchedule、matchMetadata、getDeliveryManifest 和 autoDispatch 的文档。

PUT 请求

更新端点内的文档

update("<24_digit_ID>", $data);

update() 的示例

$newData = [
  "name" => "Jack Driver",
];

$onfleet->workers->update("<24_digit_ID>", $newData);

insertTask() 的示例

$onfleet->workers->insertTask("<24_digit_ID>", $data);

DELETE 请求

删除端点内的文档

deleteOne("<24_digit_ID>");

deleteOne() 的示例

$onfleet->workers->deleteOne("<24_digit_ID>");

使用 CRUD 操作的示例

• 获取所有接收者

  try {
    $tasks = $onfleet->tasks->get([ "from" =>"1557936000000", "to" => "1558022400000" ]);
    foreach ($tasks['tasks'] as $task) {
      if (is_set($task['recipients'][0])) {
        // Do something with the recipients
      }
    }
  } catch (Exception $error) {
    // Do something with the error
  }

不要做的事情

• 低效的模式，请使用元数据代替

  // DONT
  try {
    $workers = $onfleet->workers.get();
    for ($workers as $worker) {
      foreach ($worker['metadata'] as $metadataEntry) {
        if ($metadataEntry['name'] === "hasFreezer" && $metadataEntry['value']) {
          // Do something
        }
      }
    }
  } catch (Exception $error) {
    // Do something with the error
  }
  
  // DO
  try {
    $workers = $onfleet->workers->matchMetadata([["name" => "hasFreezer", "type" => "boolean", "value" => true]]);
    for ($workers as $worker) {
      // Do something
    }
  } catch (Exception $error) {
    // Do something with the error
  }

返回顶部.