讲师中心 微信公众号

工具推荐

视频效率加速
AniShort
AniShort

AI短剧协同制作平台

立刻MV
立刻MV

低成本歌曲 MV、视频生成

Seko
Seko

AI短剧一键生成成片

SoundView
SoundView

字幕擦除翻译、配音口型同步

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

大浩小哥_7956

大浩小哥_7956

发布时间:2025-09-22 13:10:19

|

431人浏览过

|

来源于php中文网

原创

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();
        }
    }
}

代码解析与关键点

  1. 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);:设置用于比较的值。
  2. FilterGroup的创建与封装:

    Build MCP servers and clients for PHP applications with the official PHP SDK
    Build MCP servers and clients for PHP applications with the official PHP SDK

    使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。

    下载
    • $filterGroup = new FilterGroup();:实例化一个FilterGroup对象。
    • $filterGroup->setFilters([$filter]);:这是解决问题的关键一步。将创建好的$filter实例放入一个数组中,然后传递给FilterGroup的setFilters()方法。即使只有一个Filter,也需要将其封装在数组中。
  3. PublicObjectSearchRequest的构建:

    • $searchRequest = new PublicObjectSearchRequest();:实例化搜索请求对象。
    • $searchRequest->setFilterGroups([$filterGroup]);:将封装了Filter的$filterGroup实例放入一个数组中,然后传递给PublicObjectSearchRequest的setFilterGroups()方法。同样,即使只有一个FilterGroup,也需要将其封装在数组中。
  4. 执行搜索与结果处理:

    • $this->hubspot_client->crm()->companies()->searchApi()->doSearch($searchRequest);:通过HubSpot客户端调用公司的搜索API。
    • $response['results'][0]['id'];:HubSpot API的搜索结果通常包含在results数组中。每个元素是一个匹配的对象。这里我们获取第一个匹配公司的id属性。在实际应用中,可能需要遍历results数组以处理所有匹配项。
  5. 异常处理:

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

热门AI工具

更多
DeepSeek

DeepSeek是一款面向对话、写作、编程和推理场景的AI大模型工具。

花生AI
花生AI Hot

一款AI视频创作工具,主要用于B站推出的AI视频创作工具,适合需要提升相关任务效率的用户。

VibeKnow
VibeKnow Hot

一款AI视频创作工具,主要用于全球首个AI知识视频创作平台,文档、文章、网页,一键生成视频,适合需要提升相关任务效率的用户。

豆包大模型

豆包大模型是一款由字节跳动推出的企业级大语言模型服务平台。

火山引擎

火山引擎是一款面向企业的云计算与AI服务平台。

WorkBuddy

一款AI办公效率工具,主要用于腾讯云推出的AI原生桌面智能体工作台,适合需要提升相关任务效率的用户。

墨刀AI
墨刀AI Hot

一款AI图像与设计工具,主要用于产品经理的专属智能体,适合需要提升相关任务效率的用户。

Laper
Laper Hot

Laper是专为编剧、导演和制片人推出的 AI 原生剧本创作工具。

SoundView
SoundView Hot

SoundView是一款面向跨境电商的视频翻译、配音和本地化 AI 创作平台。

相关专题

更多
js 字符串转数组
js 字符串转数组

js字符串转数组的方法:1、使用“split()”方法;2、使用“Array.from()”方法;3、使用for循环遍历;4、使用“Array.split()”方法。本专题为大家提供js字符串转数组的相关的文章、下载、课程内容,供大家免费下载体验。

1978

2023.08.03

js截取字符串的方法
js截取字符串的方法

js截取字符串的方法有substring()方法、substr()方法、slice()方法、split()方法和slice()方法。本专题为大家提供字符串相关的文章、下载、课程内容,供大家免费下载体验。

3324

2023.09.04

java基础知识汇总
java基础知识汇总

java基础知识有Java的历史和特点、Java的开发环境、Java的基本数据类型、变量和常量、运算符和表达式、控制语句、数组和字符串等等知识点。想要知道更多关于java基础知识的朋友,请阅读本专题下面的的有关文章,欢迎大家来php中文网学习。

6484

2023.10.24

字符串介绍
字符串介绍

字符串是一种数据类型,它可以是任何文本,包括字母、数字、符号等。字符串可以由不同的字符组成,例如空格、标点符号、数字等。在编程中,字符串通常用引号括起来,如单引号、双引号或反引号。想了解更多字符串的相关内容,可以阅读本专题下面的文章。

6789

2023.11.24

java读取文件转成字符串的方法
java读取文件转成字符串的方法

Java8引入了新的文件I/O API,使用java.nio.file.Files类读取文件内容更加方便。对于较旧版本的Java,可以使用java.io.FileReader和java.io.BufferedReader来读取文件。在这些方法中,你需要将文件路径替换为你的实际文件路径,并且可能需要处理可能的IOException异常。想了解更多java的相关内容,可以阅读本专题下面的文章。

8294

2024.03.22

php中定义字符串的方式
php中定义字符串的方式

php中定义字符串的方式:单引号;双引号;heredoc语法等等。想了解更多字符串的相关内容,可以阅读本专题下面的文章。

13034

2024.04.29

go语言字符串相关教程
go语言字符串相关教程

本专题整合了go语言字符串相关教程,阅读专题下面的文章了解更多详细内容。

6799

2025.07.29

c++字符串相关教程
c++字符串相关教程

本专题整合了c++字符串相关教程,阅读专题下面的文章了解更多详细内容。

7687

2025.08.07

Nginx CVE-2026-123007排查与防护指南
Nginx CVE-2026-123007排查与防护指南

Nginx HTTP/2漏洞该怎么修复?本专题围绕CVE-2026-123007,介绍安全版本升级、模块兼容检查和配置恢复方法,以及日志排查、权限设置等后续加固操作,方便你按实际部署情况查找对应教程。

0

2026.11.20

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
墨刀帮助中心
墨刀帮助中心

共0课时 | 0人学习

MyEclipse学习中心
MyEclipse学习中心

共0课时 | 0人学习

关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号
PHP中文网订阅号
每天精选资源文章推送

Copyright 2014-2026 https://www.php.cn/ All Rights Reserved | php.cn