Nesta postagem do blog, você verá:
- O que é a especificação OpenAPI.
- Por que ela é tão popular para a definição de ferramentas em estruturas e plataformas de IA.
- Como a Bright Data oferece suporte ao OpenAPI para integração simplificada em agentes e fluxos de trabalho de IA.
- A especificação OpenAPI da API Bright Data Web Unlocker.
- A especificação OpenAPI da API SERP da Bright Data.
- Como essas especificações funcionam na prática em uma plataforma de IA do mundo real
Vamos mergulhar no assunto!
O que é a especificação OpenAPI?
A especificação OpenAPI (OAS) é um padrão aberto, independente de linguagem, para descrever APIs RESTful. Ela fornece um formato estruturado e legível por máquina (normalmente YAML ou JSON) para definir as operações, parâmetros, respostas, esquemas de segurança e outras características de uma API.
Explore o repositório GitHub para ver a especificação!
Observação: a especificação OpenAPI era originalmente chamada de “especificação Swagger”. Portanto, se você está procurando por “especificações Bright Data Swagger”, você está no lugar certo!
Por que muitas soluções de IA dependem das especificações OpenAPI para definição de ferramentas
Muitas estruturas de IA adotam o suporte OpenAPI para definição de ferramentas. A principal razão é que a especificação OpenAPI fornece um contrato padronizado e legível por máquina que descreve exatamente o que uma API externa faz.
Essa padronização traz três benefícios principais:
- Interoperabilidade e atrito mínimo: a OpenAPI é um padrão amplamente suportado. Depois de fornecer uma especificação, a plataforma pode importar automaticamente a API, gerar formulários de entrada, chamadas e tratamento de respostas e integrá-la às suas ferramentas.
- Curva de aprendizado reduzida: mesmo usuários não técnicos podem criar ferramentas usando APIs simplesmente copiando as especificações OpenAPI da documentação ou de outras fontes. Assim, não há necessidade de conexões manuais ou codificação, e é por isso que o suporte a OpenAPI é tão comum em plataformas de IA de baixo ou nenhum código.
- Melhor manutenção: com um contrato de API explícito, as atualizações são fáceis. Quando a API evolui, você só precisa atualizar a especificação na definição da ferramenta, simplificando muito a manutenção e reduzindo a necessidade de grandes reescritas.
Em resumo, definir ferramentas por meio da OpenAPI abre as portas para um ecossistema pronto para empresas, onde CRMs, provedores de dados, APIs internas e outros serviços externos podem ser conectados, documentados e mantidos com segurança, com o mínimo de sobrecarga manual em agentes de IA, pipelines e fluxos de trabalho.
Apresentando as especificações OpenAPI da Bright Data
A Bright Data vem com um conjunto de produtos e serviços para extração de dados da web, interação automatizada com a web, rastreamento da web e muito mais.
Essas soluções estão disponíveis por meio de APIs (e também por meio de opções sem código), o que significa que você pode configurá-las usando as especificações OpenAPI em plataformas de IA que suportam esse recurso.
Neste artigo, vamos nos concentrar em duas das ferramentas mais importantes da Bright Data:
- API SERP: extrai automaticamente dados estruturados de mecanismos de pesquisa como Google, Bing e Yandex. Ela lida com tarefas complexas, como gerenciamento de Proxy, Resolução de CAPTCHA e renderização de JavaScript, permitindo que você receba resultados limpos e em tempo real no formato JSON ou HTML sem ser bloqueado.
- API Web Unlocker: contorna medidas anti-bot complexas (como CAPTCHAs, bloqueios de IP e impressão digital) para extrair dados da web de qualquer página da web. Ela atua como um intermediário, gerenciando Proxies, emulando usuários reais e fornecendo respostas limpas em HTML, JSON e Markdown.
Para cada serviço, você verá a especificação OpenAPI 3.x nos formatos YAML e JSON, bem como exemplos de testes no Swagger Editor.
A partir dessas especificações, você pode converter APIs de Scraping de dados e outros pontos de extremidade de API em especificações OpenAPI para integração com IA.
Observação: alguns produtos da Bright Data compartilham os mesmos pontos finais de API, alterando o comportamento com base apenas no corpo da solicitação. Como você não pode definir duas especificações completamente separadas para o mesmo caminho e método em um único documento OpenAPI, você precisa de especificações OpenAPI separadas. É por isso que forneceremos duas especificações OpenAPI dedicadas para a API SERP e a API Web Unlocker (já que elas compartilham o mesmo ponto final).
Especificação OpenAPI da API Web Unlocker
Descubra a especificação OpenAPI para a API Web Unlocker da Bright Data.
Observação: para obter mais detalhes, verifique os argumentos, opções, métodos de autenticação disponíveis e muito mais nas seguintes páginas da documentação:
Especificação YAML
Esta é a especificação OpenAPI YAML para a API Web Unlocker da Bright Data:
openapi: 3.0.4
info:
title: Web Unlocker da Bright Data
version: 1.0.0
description: |
A Web Unlocker da Bright Data permite que você contorne medidas anti-bot, gerencie Proxies e realize a resolução de CAPTCHAs automaticamente para facilitar a coleta de dados da web.
[Documentação da API Web Unlocker](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)
contact:
name: Bright Data
url:
servers:
- url: https://api.brightdata.com
tags:
- name: Web Unlocker
description: Operações para interagir com a API do Bright Data Web Unlocker.
componentes:
esquemas de segurança:
BearerAuth:
tipo: http
esquema: bearer
formato do portador: BRIGHT_DATA_API_KEY
caminhos:
/request:
post:
operationId: sendWebUnlockerRequest
resumo: Enviar uma solicitação da API do Web Unlocker
descrição: |
Envie uma solicitação da API Web Unlocker usando sua zona da API Bright Data Web Unlocker.
[Documentação da API Web Unlocker `/request`](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)
tags:
- Web Unlocker
segurança:
- BearerAuth: []
requestBody:
obrigatório: verdadeiro
conteúdo:
application/json:
esquema:
tipo: objeto
obrigatório:
- zona
- url
- formato
propriedades:
zona:
tipo: string
descrição: O nome da sua zona Web Unlocker.
url:
tipo: string
descrição: A URL do site de destino a ser desbloqueada e buscada.
exemplo: https://example.com/products
formato:
tipo: string
descrição: |
Formato da resposta.
Valores permitidos:
- `raw`: Retorna a resposta imediatamente no corpo.
- `json`: Retorna a resposta como um objeto JSON estruturado.
padrão: raw
método:
tipo: string
descrição: Método HTTP usado ao buscar o URL de destino.
exemplo: GET
país:
tipo: string
descrição: |
Código do país para localização do Proxy (formato ISO 3166-1 alfa-2).
exemplo: us
formato_dos_dados:
tipo: string
descrição: |
Formato dos dados de saída extraídos.
Valores permitidos:
- `markdown`: Conteúdo da página convertido para Markdown.
- `screenshot`: Para capturar uma imagem PNG da página renderizada.
enum:
- markdown
- screenshot
responses:
"200":
descrição: Resposta bem-sucedida contendo resultados de pesquisa.
"400":
descrição: Solicitação inválida (campos obrigatórios ausentes ou parâmetros inválidos).
"401":
descrição: Não autorizado (chave API Bright Data inválida ou ausente).Observação:
A seção securitySchemes especifica um esquema de segurança que usa autenticação HTTP bearer. Em detalhes, os clientes devem enviar uma BRIGHT_DATA_API_KEY como um token bearer no cabeçalho Authorization ao chamar a API.
Ao mesmo tempo, a maioria das plataformas de IA já inclui métodos de autenticação integrados e pode ignorar esse campo de especificação. Ainda assim, é útil incluí-lo na especificação OpenAPI para maior clareza e referência.
Especificação JSON
Abaixo está a especificação JSON OpenAPI para a API Web Unlocker:
{
"openapi": "3.0.4",
"info": {
"title": "Bright Data Web Unlocker API",
"version": "1.0.0",
"description": "A API Bright Data Web Unlocker permite que você contorne medidas anti-bot, gerencie Proxies e resolva CAPTCHAs automaticamente para facilitar a coleta de dados da web.nn[Documentação da API Web Unlocker](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)n",
"contact": {
"name": "Bright Data",
"url": ""
}
},
"servidores": [
{
"url": "https://api.brightdata.com"
}
],
"tags": [
{
"nome": "Web Unlocker",
"descrição": "Operações para interagir com a API Bright Data Web Unlocker."
}
],
"componentes": {
"esquemas de segurança": {
"BearerAuth": {
"tipo": "http",
"esquema": "bearer",
"formato do portador": "BRIGHT_DATA_API_KEY"
}
}
},
"paths": {
"/request": {
"post": {
"operationId": "sendWebUnlockerRequest",
"summary": "Enviar uma solicitação da API Web Unlocker",
"description": "Envie uma solicitação da API Web Unlocker usando sua zona da API Bright Data Web Unlocker. nn[Documentação da API Web Unlocker `/request`](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)n",
"tags": [
"Web Unlocker"
],
"segurança": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"zone",
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "O nome da sua zona do Web Unlocker."
},
"url": {
"type": "string",
"description": "URL do site de destino a ser desbloqueado e buscado.",
"example": "https://example.com/products"
},
"format": {
"type": "string",
"description": "Formato da resposta. nValores permitidos: n- `raw`: Retorna a resposta imediatamente no corpo. n- `json`: Retorna a resposta como um objeto JSON estruturado. n",
"default": "raw"
},
"method": {
"type": "string",
"description": "Método HTTP usado ao buscar a URL de destino.",
"example": "GET"
},
"country": {
"type": "string",
"description": "Código do país para localização do Proxy (formato ISO 3166-1 alfa-2). n",
"example": "us"
},
"data_format": {
"type": "string",
"description": "Formato dos dados de saída extraídos. nValores permitidos:n- `markdown`: Conteúdo da página convertido para Markdown.n- `screenshot`: Para capturar uma imagem PNG da página renderizada.n",
"enum": [
"markdown",
"screenshot"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Resposta bem-sucedida contendo resultados da pesquisa."
},
"400": {
"description": "Solicitação inválida (campos obrigatórios ausentes ou parâmetros inválidos)."
},
"401": {
"description": "Não autorizado (chave API Bright Data inválida ou ausente)."
}
}
}
}
}
}Testando no Swagger Editor
Teste a especificação OpenAPI colando-a no Swagger Editor:
Especificação OpenAPI da API SERP
Explore a especificação OpenAPI para a API SERP da Bright Data.
Observação: para obter mais informações, consulte os argumentos, opções, métodos de autenticação e muito mais nas seguintes páginas da documentação:
Especificação YAML
Aqui está a especificação OpenAPI YAML para a API SERP:
openapi: 3.0.4
info:
title: API SERP da Bright Data
version: 1.0.0
description: |
Extraia resultados de mecanismos de pesquisa usando a API SERP da Bright Data. Extraia dados estruturados dos principais mecanismos de pesquisa, incluindo Google, Bing, Yandex, DuckDuckGo e muito mais.
Obtenha resultados orgânicos, anúncios pagos, listagens locais, resultados de compras e outros recursos SERP.
[Documentação da API SERP](https://docs.brightdata.com/scraping-automation/serp-api/introduction)
contact:
name: Bright Data
url:
servers:
- url: https://api.brightdata.com
tags:
- name: SERP
description: Operações relacionadas à API SERP da Bright Data.
componentes:
esquemas de segurança:
BearerAuth:
tipo: http
esquema: bearer
formato do portador: BRIGHT_DATA_API_KEY
caminhos:
/request:
post:
operationId: sendSerpRequest
resumo: Enviar uma solicitação da API SERP
descrição: |
Envie uma solicitação da API SERP usando sua zona da API SERP da Bright Data.
[Documentação da API SERP `/request`](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)
tags:
- SERP
segurança:
- BearerAuth: []
requestBody:
obrigatório: verdadeiro
conteúdo:
application/json:
esquema:
tipo: objeto
obrigatório:
- zona
- url
- formato
propriedades:
zona:
tipo: string
descrição: O nome da sua zona API SERP.
url:
tipo: string
descrição: A URL do mecanismo de pesquisa a ser consultada (por exemplo, `https://www.google.com/search?q=<search_query>`).
exemplo: https://www.google.com/search?q=pizza&hl=en&gl=us
formato:
tipo: string
descrição: |
Formato da resposta.
Valores permitidos:
- `raw`: Retorna a resposta imediatamente no corpo.
- `json`: Retorna a resposta como um objeto JSON estruturado.
padrão: raw
enum:
- raw
- json
país:
tipo: string
descrição: |
Código do país para localização do Proxy (formato ISO 3166-1 alfa-2).
exemplo: us
data_format:
tipo: string
descrição: |
Formato dos dados de saída SERP.
Valores permitidos:
- `json`: Dados JSON totalmente analisados com resultados SERP estruturados, incluindo orgânicos, pagos, locais, compras e trechos de destaque.
- `markdown`: Conteúdo SERP convertido para Markdown.
enum:
- json
- markdown
respostas:
"200":
descrição: Resposta bem-sucedida contendo resultados de pesquisa.
"400":
descrição: Solicitação inválida (campos obrigatórios ausentes ou parâmetros inválidos).
"401":
descrição: Não autorizado (chave API Bright Data inválida ou ausente).Especificação JSON
Esta é a especificação JSON OpenAPI para a API SERP:
{
"openapi": "3.0.4",
"info": {
"title": "Bright Data SERP API",
"version": "1.0.0",
"description": "Extraia resultados de mecanismos de pesquisa usando a API SERP da Bright Data. Extraia dados estruturados dos principais mecanismos de pesquisa, incluindo Google, Bing, Yandex, DuckDuckGo e muito mais. nObtenha resultados orgânicos, anúncios pagos, listagens locais, resultados de compras e outros recursos SERP.n[Documentação da API SERP](https://docs.brightdata.com/scraping-automation/serp-api/introduction)n",
"contact": {
"name": "Bright Data",
"url": ""
}
],
"servers": [
{
"url": "https://api.brightdata.com"
}
],
"tags": [
{
"name": "SERP",
"description": "Operações relacionadas à API SERP da Bright Data."
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "BRIGHT_DATA_API_KEY"
}
}
},
"paths": {
"/request": {
"post": {
"operationId": "sendSerpRequest",
"summary": "Enviar uma solicitação da API SERP",
"description": "Envie uma solicitação da API SERP usando sua zona da API SERP da Bright Data. nn[Documentação da API SERP `/request`](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)n",
"tags": [
"SERP"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"Zona",
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "O nome da sua zona API SERP."
},
"url": {
"tipo": "string",
"descrição": "A URL do mecanismo de pesquisa a ser consultada (por exemplo, `https://www.google.com/search?q=<search_query>`).",
"example": "https://www.google.com/search?q=pizza&hl=en&gl=us"
},
"format": {
"type": "string",
"description": "Formato da resposta. nValores permitidos: n- `raw`: Retorna a resposta imediatamente no corpo. n- `json`: Retorna a resposta como um objeto JSON estruturado. n",
"default": "raw",
"enum": [
"raw",
"json"
]
},
"country": {
"type": "string",
"description": "Código do país para localização do Proxy (formato ISO 3166-1 alfa-2). n",
"example": "us"
},
"data_format": {
"type": "string",
"description": "Formato dos dados de saída SERP. nValores permitidos:n- `json`: Dados JSON totalmente analisados com resultados SERP estruturados, incluindo orgânicos, pagos, locais, compras e trechos de recursos.n- `markdown`: Conteúdo SERP convertido para Markdown. n",
"enum": [
"json",
"markdown"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Resposta bem-sucedida contendo resultados de pesquisa."
},
"400": {
"description": "Solicitação inválida (campos obrigatórios ausentes ou parâmetros inválidos)."
},
"401": {
"description": "Não autorizado (chave API Bright Data inválida ou ausente)."
}
}
}
}
}
}Testando no Swagger Editor
Para testar esta especificação, cole-a no Editor Swagger online:
Testando as especificações OpenAPI da Bright Data para integração de ferramentas no Dify
Para verificar se as especificações OpenAPI acima para conexão com os serviços Bright Data via API funcionam, vamos testá-las no Dify.
Especificamente, testaremos a especificação OpenAPI da API SERP da Bright Data, mas você pode facilmente adaptar esta seção guiada a outras especificações SERP da API Web Unlocker também.
O Dify é uma plataforma de desenvolvimento de código aberto e baixo código que simplifica a criação, implantação e gerenciamento de aplicativos alimentados por IA. Entre seus muitos recursos, ele permite definir ferramentas personalizadas usando especificações OpenAPI.
Essa capacidade não é exclusiva do Dify. Muito pelo contrário, muitas outras plataformas de criação de agentes de IA, especialmente soluções de baixo código/sem código ou prontas para uso corporativo, também oferecem suporte à integração de ferramentas por meio de especificações OpenAPI.
Explore integrações adicionais com a Bright Data por meio das especificações OpenAPI nos seguintes guias:
- Integre a API SERP da Bright Data a um agente de IA no Microsoft Copilot Studio
- Integre a API SERP da Bright Data a um agente de IA no IBM watsonx
Agora, vamos testar as especificações OpenAPI da Bright Data no Dify!
Pré-requisitos
Para seguir esta seção do tutorial, você precisa de:
- Uma conta Bright Data com uma chave API e uma zona API SERP configurada.
- Uma conta Dify Cloud para usar a versão em nuvem ou uma instância local do Dify em execução em sua máquina.
Siga o guia oficial para gerar uma chave API da Bright Data. Guarde-a em um local seguro, pois precisaremos dela para autenticar as chamadas da ferramenta API SERP.
Em seguida, siga as instruções na documentação da Bright Data para configurar uma zona API SERP em sua conta:
A partir de agora, vamos supor que sua zona API SERP se chama serp_api. Certifique-se de adaptar o nome da zona nos exemplos para corresponder ao nome da sua zona.
Etapa 1: crie uma nova ferramenta personalizada
Faça login na sua conta Dify Cloud ou inicie sua instância local. Para criar uma nova ferramenta personalizada, comece selecionando a opção “Ferramentas” no menu superior:
Na página “Ferramentas”, vá para a guia “Personalizado”:
Na guia “Personalizado”, clique no cartão “Criar ferramenta personalizada”:
O seguinte modal “Criar ferramenta personalizada” será exibido:
Ótimo! É aqui que você colará sua especificação OpenAPI da API SERP da Bright Data.
Etapa 2: definir a ferramenta API SERP usando a especificação OpenAPI
No modal “Criar ferramenta personalizada”, dê um nome à ferramenta, como “API SERP”. No campo “Esquema”, cole a especificação YAML OpenAPI para a API SERP da Bright Data.
Você deverá ver algo assim:
Observe que a seção “Ferramentas disponíveis” é preenchida automaticamente com base na definição fornecida na especificação OpenAPI.
Como previsto anteriormente, a maioria das plataformas exige que você defina a autenticação por meio de um método integrado. Nesse caso, para fazer isso, clique no ícone de engrenagem na seção “Método de autenticação”:
Configure a autenticação da seguinte forma:
- Tipo de autenticação: “Cabeçalho”
- Tipo: “Portador”
- Chave: “Autorização”
- Valor: Cole sua chave API da Bright Data
Isso configura a autenticação por meio de um cabeçalho de autorização, que será enviado como:
Portador <SUA_CHAVE_API_BRIGHT_DATA>Esse é precisamente o método de autenticação suportado pelas APIs da Bright Data.
Ótimo! A ferramenta API SERP agora foi definida e configurada corretamente.
Etapa 3: Teste a ferramenta
Na seção “Ferramentas disponíveis”, localize a linha do endpoint /request configurado e clique no botão “Testar”:
Isso abrirá o modal “Testar sendSerpRequest”, onde você pode personalizar parâmetros e valores para verificar se a ferramenta configurada funciona.
Por exemplo, comece testando uma resposta básica no formato JSON. O resultado esperado é uma resposta JSON estruturada contendo a página SERP extraída do Google no formato HTML (o formato de dados padrão da API SERP):
Role para baixo até a seção “Resultados do teste” para visualizar a resposta da API. Você verá que o campo do corpo no JSON contém o HTML da página SERP, conforme esperado:
Fantástico! Este resultado corresponde às expectativas.
Agora, tente obter a versão Markdown da mesma página diretamente no corpo da resposta:
Observe como, desta vez, a resposta é um texto simples (porque format: raw) contendo os dados SERP no formato Markdown (devido a data_format: markdown) —pronto para ingestão LLM.
Agora que você sabe que a ferramenta funciona (porque ela chama com sucesso a API subjacente), você pode integrá-la a qualquer fluxo de trabalho Dify ou agente de IA.
Et voilà! A ferramenta Bright Data definida por meio da especificação OpenAPI funciona perfeitamente.
Conclusão
Neste artigo, você aprendeu por que as plataformas e bibliotecas de IA permitem o uso de especificações OpenAPI para definição de ferramentas e como a Bright Data oferece suporte a essa opção. Em particular, você viu as especificações OpenAPI para as soluções Web Unlocker e API SERP da Bright Data.
Ao integrar essas duas ferramentas, você pode criar agentes de IA complexos que pesquisam na web e recuperam dados da web para RAG, pesquisa profunda e muitas outras tarefas. Aproveite o conjunto completo de serviços de API da Bright Data para IA e libere todo o potencial dos seus agentes!
Crie uma conta Bright Data gratuitamente hoje mesmo e comece a integrar nossas APIs para recuperação de dados da web!
