HubSpot API 公司搜索：精确筛选的正确姿势-php教程-PHP中文网

HubSpot API 公司搜索：精确筛选的正确姿势

霞舞

发布： 2025-09-22 13:10:19

原创

357人浏览过

HubSpot API 公司搜索：精确筛选的正确姿势

在使用HubSpot API进行公司搜索时，若过滤条件设置不当，可能导致API返回所有公司而非目标公司。本文旨在详细阐述如何正确构建Filter和FilterGroup，并将其应用于PublicObjectSearchRequest，以实现基于域名等属性的精确搜索。通过遵循正确的过滤逻辑，开发者可以避免获取无关数据，显著提高API调用的准确性和效率。

理解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代码示例。

示例代码：通过域名搜索公司

<?php

namespace App\Services;

use HubSpot\Client\Crm\Companies\Model\Filter;
use HubSpot\Client\Crm\Companies\Model\FilterGroup;
use HubSpot\Client\Crm\Companies\Model\PublicObjectSearchRequest;
use HubSpot\Client\ApiException;
use HubSpot\Client\Crm\Companies\Api\SearchApi; // 假设这是你的HubSpot客户端

class CompanyService
{
    private $hubspot_client; // 假设已注入或初始化HubSpot客户端

    public function __construct($hubspot_client)
    {
        $this->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-youjiankuohaophpcnsetPropertyName('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的构建：

纳米搜索
纳米搜索：360推出的新一代AI搜索引擎

30

查看详情
- $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接收到符合其期望的数据结构。这种结构化的过滤方法不仅提高了搜索的准确性，也为构建更复杂的查询提供了基础。

以上就是HubSpot API 公司搜索：精确筛选的正确姿势的详细内容，更多请关注php中文网其它相关文章！