理解HubSpot API的过滤机制
hubspot的crm api在进行对象（如公司、联系人）搜索时，提供了一套灵活的过滤机制。核心概念包括filter（过滤器）和filtergroup（过滤器组）。
- Filter：定义了单个过滤条件，例如“属性名是domain，操作符是EQ（等于），值为hubspot.com”。
- FilterGroup：是一个或多个Filter的集合。在一个FilterGroup内部，多个Filter之间默认是逻辑与（AND）关系。PublicObjectSearchRequest可以接受一个或多个FilterGroup，不同FilterGroup之间是逻辑或（OR）关系。
最初的问题在于，开发者尝试将Filter实例直接传递给PublicObjectSearchRequest的setFilterGroups()方法，而该方法期望的是一个FilterGroup实例数组。这导致API无法正确解析过滤条件，从而返回了所有公司记录。
正确构建公司搜索请求
要实现精确的公司搜索，关键在于将Filter封装到FilterGroup中，然后再将FilterGroup传递给PublicObjectSearchRequest。以下是正确的构建步骤和相应的PHP代码示例。
示例代码：通过域名搜索公司
hubspot_client = $hubspot_client;
}
/**
* 通过公司域名搜索公司并返回其ID。
*
* @param string $company_domain 要搜索的公司域名，例如 'hubspot.com'
* @return string|null 公司ID或错误信息
*/
public function searchCompany(string $company_domain): ?string
{
// 1. 创建一个Filter实例，定义单个过滤条件
$filter = new Filter();
$filter->setPropertyName('domain'); // 设置要过滤的属性名，这里是 'domain'
$filter->setOperator('EQ'); // 设置操作符，'EQ' 表示等于
$filter->setValue($company_domain); // 设置属性值，即要搜索的域名
// 2. 创建一个FilterGroup实例，并将Filter添加到其中
// FilterGroup可以包含多个Filter，它们之间是逻辑AND关系
$filterGroup = new FilterGroup();
$filterGroup->setFilters([$filter]); // 将单个Filter封装到FilterGroup中
// 3. 创建PublicObjectSearchRequest实例，并将FilterGroup添加到其中
// setFilterGroups() 期望一个FilterGroup实例数组
$searchRequest = new PublicObjectSearchRequest();
$searchRequest->setFilterGroups([$filterGroup]); // 将FilterGroup数组传递给搜索请求
try {
// 4. 执行搜索请求
/** @var \HubSpot\Client\Crm\Companies\Model\CollectionResponseWithPublicObjectId $response */
$response = $this->hubspot_client->crm()->companies()->searchApi()->doSearch($searchRequest);
// 5. 处理响应结果
if (!empty($response['results']) && isset($response['results'][0]['id'])) {
return $response['results'][0]['id']; // 返回第一个匹配公司的ID
} else {
return null; // 未找到匹配公司
}
} catch (ApiException $e) {
// 6. 异常处理
error_log("Exception when calling search_api->do_search: " . $e->getMessage());
return "Exception when calling search_api->do_search: " . $e->getMessage();
}
}
}代码解析与关键点
-
Filter的创建与配置：
- $filter = new Filter();：实例化一个Filter对象。
- $filter->setPropertyName('domain');：指定要基于哪个公司属性进行过滤。这里是domain（公司域名）。HubSpot中公司对象的常见属性还包括name（公司名称）、hs_object_id（HubSpot内部ID）等。
- $filter->setOperator('EQ');：设置比较操作符。EQ表示“等于”。其他常用的操作符包括NEQ（不等于）、CONTAINS_TOKEN（包含指定字符串）、GT（大于）、LT（小于）等。
- $filter->setValue($company_domain);：设置用于比较的值。
-
FilterGroup的创建与封装：
- $filterGroup = new FilterGroup();：实例化一个FilterGroup对象。
- $filterGroup->setFilters([$filter]);：这是解决问题的关键一步。将创建好的$filter实例放入一个数组中，然后传递给FilterGroup的setFilters()方法。即使只有一个Filter，也需要将其封装在数组中。
-
PublicObjectSearchRequest的构建：
- $searchRequest = new PublicObjectSearchRequest();：实例化搜索请求对象。
- $searchRequest->setFilterGroups([$filterGroup]);：将封装了Filter的$filterGroup实例放入一个数组中，然后传递给PublicObjectSearchRequest的setFilterGroups()方法。同样，即使只有一个FilterGroup，也需要将其封装在数组中。
-
执行搜索与结果处理：
- $this->hubspot_client->crm()->companies()->searchApi()->doSearch($searchRequest);：通过HubSpot客户端调用公司的搜索API。
- $response['results'][0]['id'];：HubSpot API的搜索结果通常包含在results数组中。每个元素是一个匹配的对象。这里我们获取第一个匹配公司的id属性。在实际应用中，可能需要遍历results数组以处理所有匹配项。
-
异常处理：
- try...catch (ApiException $e)：始终建议对API调用进行异常处理，以捕获网络问题、API限流、权限不足等错误，并提供健壮的错误报告。
注意事项与最佳实践
- 属性名准确性：确保setPropertyName()中使用的属性名与HubSpot中实际的属性内部名称（internal name）一致。可以在HubSpot后台的“设置”->“属性”中查看。
- 操作符选择：根据您的搜索需求选择正确的setOperator()。不正确的操作符可能导致无结果或结果不准确。
- 结果分页：对于可能返回大量结果的搜索，PublicObjectSearchRequest还支持设置limit（每页结果数）和after（用于分页的偏移量），以实现结果的分页加载。
-
多条件搜索：
- 逻辑与（AND）：在同一个FilterGroup中添加多个Filter，它们之间是AND关系。
- 逻辑或（OR）：在PublicObjectSearchRequest的setFilterGroups()方法中传递多个FilterGroup，它们之间是OR关系。
- 错误日志：在生产环境中，务必将API调用中捕获的异常记录到日志中，以便于问题排查。
总结
通过遵循上述指南，开发者可以有效地利用HubSpot API的过滤机制，精确地搜索公司数据。核心在于正确理解和使用Filter与FilterGroup的层级关系，确保PublicObjectSearchRequest接收到符合其期望的数据结构。这种结构化的过滤方法不仅提高了搜索的准确性，也为构建更复杂的查询提供了基础。
