README

Airtable的现代PHP API客户端。

安装

通过Composer

composer require guym4c/airtable-client

使用方法

获取客户端的一个实例

$airtable = new \Guym4c\Airtable\Airtable(/* YOUR API KEY */, /* YOUR BASE ID */);

现在您可以访问您基础表中的表的CRUD（创建、读取、更新、删除）操作。

$airtable->get($table, $recordId);
$airtable->create($table, $jsonArray);
$airtable->update($record /* more on this below */); // you may pass an additional boolean as TRUE for a destructive update
$airtable->delete($table, $recordId); // returns a boolean - whether deletion was successful

记录

客户端在获取、创建和更新操作后将为Record提供实例。Record公开了表、Airtable ID、JSON数据数组和从Airtable获取的时间的getter。

您还可以将记录中的字段作为Record的属性访问

$myField = $record->field;

当您的Airtable字段名称包含空格时，您可以使用花括号语法 - $record->{'字段名称包含空格'};。

与基础中其他表相关的字段将自动检测。如果您将字段作为属性访问，客户端不知道关系指向哪个表，并将返回一个Loader，您可以将表名传递给它以解析关系。

$relatedRecord = $record->field->load('relatedTable');

您也可以直接调用$record->load($field, $table);来直接获取相关的记录。

列出记录

您可以通过调用$airtable->list($table)获取多个记录。您可以通过传递额外的Filter参数来过滤这些结果 - 请参阅您基础表的API文档，了解Filter的属性细节。

有两种过滤简写方法：search($table, $field, $value)和find($table, $field, $value)。search()在$table的$field中执行Airtable搜索$value，因此将返回子串匹配。find()将只返回精确匹配。

由于list()结果分页，list()返回给您完成的Request对象。然后您可以使用getRecords()获取获取的Record列表，或使用nextPage()转到下一页。请注意，页面指针最终将在Airtable端重置。

批量作业

$airtable->createAll()和$airtable->updateAll()允许批量请求数据。您可以分别将这些方法和数组传递给这些方法，客户端将使用批量请求创建它们。

速率限制

Airtable API每秒限制为5个查询。如果您超过此限制，客户端将降低请求速度，阻止请求。如果Airtable端超过此限制并将您置于30秒的惩罚箱中，对API的调用将引发异常。

缓存

通常，您可能有一些数据较静止的表。为了防止它们影响您的速率限制，您可以为客户端构造函数提供一个实现Doctrine Cache接口，以及一个您认为'可缓存'的表数组。

$airtable = new \Guym4c\Airtable\Airtable($apiKey, $baseId, $cache, ['cachable_table_one', 'cachable_table_two']);

客户端将响应对未应用过滤或排序的请求的缓存请求，并尝试响应get()、search()和find()。您可以通过调用客户端的flushCache()方法来清除缓存。当客户端创建、修改或删除记录时，也会清除表的缓存。

可缓存表必须少于101条记录，因为客户端不会缓存Airtable分页的表。

高级

客户端构造函数公开了额外的参数，用于高级使用。

public function __construct(
    string $key,
    string $baseId,
    ?CacheProvider $cache = null,
    array $cachableTables = [],
    ?string $apiEndpoint = null,
    array $headers = [],
    bool $isRateLimited = true
) {

• $key（必需）：API密钥
• $baseId（必需）：Airtable基础ID
• $cache：Doctrine 缓存实例
• $cachableTables：客户端缓存的表
• $apiEndpoint：用作替代官方 Airtable API 端点的 API 端点。必须包含版本路径。
• $headers：要附加到请求中的头信息关联数组
• $isRateLimited：是否强制执行 Airtable 速率限制（默认 true）

如果您在多个应用程序中使用此客户端，当您的客户端同时尝试联系 Airtable 时，您可能会遇到速率限制。构造函数的最后三个参数提供给您，以便您可以通过中央节流代理请求到 Airtable。