Compre OS LIVROS DESTA SÉRIE
Hoje, gostaria de dar uma breve visão sobre como você pode estender a funcionalidade do Excel usando APIs REST específicas. Isso nos permite usar funcionalidades e dados interessantes e complexos que são desenvolvidos e fornecidos na Internet por provedores altamente especializados.
REST API - o que é isso realmente?
APIs REST são serviços web que se comunicam via protocolos HTTP. Eles usam métodos padronizados como GET, POST, PUT e DELETE para transferir e manipular dados entre cliente e servidor. Vários formatos de dados, como JSON e XML, são suportados.
Existem APIs para todos os propósitos imagináveis, por exemplo: para fornecer dados meteorológicos para um determinado local ou para fornecer informações de valores mobiliários. Fornecer tais informações e a infraestrutura associada é complexo, razão pela qual seu uso geralmente está sujeito a uma taxa ou é limitado. A vantagem sobre fontes de informação disponíveis gratuitamente é a baixa barreira de uso e, muitas vezes, a maior qualidade e nível de detalhes dos dados.
Para demonstrar tudo, estamos desenvolvendo dois casos de uso protótipos com base nos quais nossas próprias funções podem ser desenvolvidas. Para fazer isso, selecionamos APIs que têm uma baixa barreira de entrada (especialmente um nível gratuito ou custos baixos) e ainda oferecem benefícios reconhecíveis.
Uma pequena dica: a documentação da API fornece não apenas a definição, mas também exemplos de solicitações e respostas para as fontes de dados correspondentes (geralmente chamadas de endpoints) e métodos. Os exemplos são formulados principalmente para as linguagens de programação comuns (Python, Java, C). LLMs como o ChatGPT são capazes de converter esses exemplos diretamente em código VBA correspondente e explicá-lo com alta precisão. Na minha opinião, uma abordagem legítima para aprender e, claro, economizar tempo.
Caso de uso 1
O requisito é separar o nome de uma determinada pessoa (composto por nome e sobrenome em qualquer ordem) em "sobrenome, nome". Para fazer isso, criamos uma função do Excel no VBA.
Essa separação é uma tarefa não trivial que ocorre na prática quando, por exemplo, formulários de coleta de dados em sites não fornecem campos separados para nome e sobrenome.
Exemplos:
"Max Müller" --> "Müller, Max"
"Stefan Johannes Meier" --> "Meier, Stefan Johannes"
Caso de uso 2
Queremos criar uma função do Excel que retorne uma resposta correspondente como uma string de um prompt fornecido usando um modelo de linguagem OpenAI. Então usamos o ChatGPT na célula do Excel.
Este caso de uso serve para ilustrar a conexão da API. Nesta forma, ele não tem nenhuma relevância prática real, mas pode servir como ponto de partida para seus próprios desenvolvimentos, incluindo complementos complexos de IA para Excel. Claro, tudo isso já existe, mas fazer você mesmo é muito melhor.
Nós dividimos os nomes
Suponha que temos uma lista de nomes e sobrenomes, cada um em uma célula. Para processamento posterior, exigimos a separação mais segura possível entre nome e sobrenome. É claro que as características específicas de cada país devem ser levadas em conta. Programar isso nós mesmos é uma tarefa complexa que não queremos assumir por vários motivos. Uma pesquisa mostra que há vários provedores de serviços web correspondentes que, entre outras coisas, resolvem essa tarefa para nós.
Como exemplo, selecionei o seguinte provedor: Namsor | Verificador de nomes para determinação de gênero, origem e etnia
Há uma API fácil de usar e bem documentada com uma cota mensal gratuita (ideal para testes).
Uma olhada no site nos mostra que há especialistas trabalhando aqui que não apenas podem separar nomes, mas também oferecem muitos outros serviços relacionados a nomes (por exemplo, derivar gênero ou origem do primeiro nome). Mas queremos focar na divisão.
O primeiro passo é se registrar para receber uma chave de API para autenticar nossas chamadas. Essa chave é então usada para verificar as cotas e atribuir informações de pagamento. Devemos manter esta chave segura.
A documentação da API nos fornece todas as informações necessárias sobre a sintaxe das solicitações e o formato das respostas. Há duas variantes: além de simplesmente fornecer o nome, você também pode fornecer informações adicionais sobre a origem da pessoa (por exemplo, o país), o que pode tornar a busca por resultados mais fácil e precisa.
#split-name-batch
#split-name-geo-batch
Por exemplo, a solicitação e a resposta para a segunda variante se parecem com isto:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameGeoBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"Ricardo Darín","countryIso2":"AR"}]}'
{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Ricardo Darín",
"nameParserType": "FN1LN1",
"nameParserTypeAlt": "FN1LN2",
"firstLastName": {
"script": null,
"id": null,
"firstName": "Ricardo",
"lastName": "Darín"
},
"score": 3.447624982163207
}
]
}
Construímos uma função VBA que faz o seguinte:
- Passando uma string contendo nome e sobrenome em qualquer ordem.
- passando opcionalmente uma string contendo o código do país no formato ISO (por exemplo, DE para Alemanha)
- O corpo JSON da solicitação é gerado a partir dos parâmetros e da nossa chave de API. O id é irrelevante para nossos propósitos porque passamos apenas um nome por solicitação.
- Enviamos uma solicitação POST para a API usando o objeto XMLHTTP. Se bem-sucedido, o resultado será retornado como um objeto JSON na resposta. Nome e sobrenome são fornecidos em campos separados.
- Para nossa função, criamos a string de retorno no formato "Sobrenome, Nome". Isso torna possível obter nomes e sobrenomes claramente durante o pós-processamento, separando as strings por vírgulas. Outros formatos de retorno também são concebíveis.
- Observação: o Excel não fornece funcionalidade interna para analisar objetos JSON. Há soluções para isso. Para manter nosso caso de uso simples, extraímos os dois campos diretamente por meio de pesquisa de string na string JSON (ExtractSepName).
Function SeparateName(name As String, Optional countryIso2 As String) As String
Dim http As Object
Dim apiKey As String
Dim url As String
Dim postData As String
Dim response As String
Dim parsedJson As Object
Dim firstName As String
Dim lastName As String
' Set your API key here
apiKey = "YOUR API KEY COMES HERE"
' Set the URL for the API
If countryIso2 = "" Then
url = "https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameBatch"
Else
url = "https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameGeoBatch"
End If
' Create the JSON data for the POST request
If countryIso2 = "" Then
postData = "{""personalNames"":[{""name"":""" & name & """}]}"
Else
postData = "{""personalNames"":[{""name"":""" & name & """,""countryIso2"":""" & countryIso2 & """}]}"
End If
' Create the HTTP object
Set http = CreateObject("MSXML2.XMLHTTP")
' Open the connection
http.Open "POST", url, False
' Set the required headers
http.setRequestHeader "X-API-KEY", apiKey
http.setRequestHeader "Accept", "application/json"
http.setRequestHeader "Content-Type", "application/json"
' Send the request with the JSON data
http.send postData
' Get the response text
response = http.responseText
If http.Status < 400 Then
SeparateName = ExtractSepName(response)
Else
SeparateName = "???"
End If
End Function
Private Function ExtractSepName(response As String) As String
Dim ipos1 As Integer, ipos2 As Integer
Dim string1 As String, string2 As String
string1 = """lastName"":"""
string2 = """firstName"":"""
ipos1 = InStr(1, response, string1) + Len(string1)
ipos2 = InStr(ipos1 + 1, response, """")
ExtractSepName = Mid(response, ipos1, ipos2 - ipos1)
ipos1 = InStr(1, response, string2) + Len(string2)
ipos2 = InStr(ipos1 + 1, response, """")
ExtractSepName = ExtractSepName & ", " & Mid(response, ipos1, ipos2 - ipos1)
End Function
No Excel agora você pode usar facilmente esta função:
Isso nos dá uma base para outras soluções.
ChatGPT na célula do Excel
Abaixo, aplicamos o mesmo princípio para chamar serviços da API OpenAI. O caso de uso é de natureza bastante teórica, mas pode servir de base para aplicações úteis.
Preparação :
Precisamos de uma chave de API para a API. Sempre há uma taxa para usar o software, mas os custos são administráveis (especialmente para aplicativos de teste) e um bom investimento para seus próprios experimentos. O faturamento é essencialmente baseado no número de tokens gerados. O modelo LLM utilizado também desempenha um papel na precificação. O site oferece boas informações sobre os custos habituais para visualizações típicas.
O processo é explicado muito bem no site da OpenAI . Depois de inserir suas informações de pagamento, você pode gerar uma chave de API (e mantê-la segura).
Queremos usar o endpoint text-generation , que (semelhante ao ChatGPT) gera uma resposta a partir de um prompt. Incorporamos isso em uma função VBA para que o prompt possa ser passado e recebamos a resposta do LLM como resultado da função. Para o nosso caso usamos o modelo gpt-4o-mini .
Observação: neste caso de uso, analisamos o objeto JSON retornado com o conversor JSON gratuito ( link ).
O código para nossa função VBA se parece com isso. Não entrarei em detalhes sobre a conversão do objeto JSON no final; o conversor mencionado acima cuida disso.
Function CallOpenAI(prompt As String) As String
Dim http As Object
Dim url As String
Dim apiKey As String
Dim response As String
Dim jsonResponse As Object
Dim jsonRequest As Object
Dim messages As Object
' Set your API key here
apiKey = "YOUR API KEY GOES HERE"
' Initialize the request
Set http = CreateObject("MSXML2.XMLHTTP")
url = "https://api.openai.com/v1/chat/completions"
' Create the JSON request body
Set jsonRequest = CreateObject("Scripting.Dictionary")
jsonRequest.Add "model", "gpt-4o-mini"
' Create the messages array
Set messages = CreateObject("Scripting.Dictionary")
messages.Add "role", "user"
messages.Add "content", prompt
Dim messagesArray As Object
Set messagesArray = CreateObject("Scripting.Dictionary")
messagesArray.Add "messages", Array(messages)
jsonRequest.Add "messages", messagesArray("messages")
' Convert the JSON request to a string
Dim jsonRequestString As String
jsonRequestString = ConvertToJson(jsonRequest)
' Send the HTTP POST request
With http
.Open "POST", url, False
.setRequestHeader "Content-Type", "application/json"
.setRequestHeader "Authorization", "Bearer " & apiKey
.send jsonRequestString
response = .responseText
End With
' Parse the JSON response
Set jsonResponse = JsonConverter.ParseJson(response)
' Output the result
CallOpenAI = jsonResponse("choices")(1)("message")("content")
End Function
É isso. Isso nos permite recuperar uma resposta do modelo no Excel simplesmente especificando um prompt.
Sim, a API, é claro, oferece muito mais possibilidades, diferentes modelos, parâmetros de ajuste, etc.
APIs REST comuns também podem ser usadas no VBA por meio de chamadas simples. A sintaxe da chamada e, especialmente, a estrutura dos dados de solicitação e resposta estão incluídas na documentação da API e podem ser facilmente transferidas para a lógica do VBA.
Ao se deparar com tarefas que parecem complexas, é sempre uma boa ideia verificar se há um serviço web que pode ser chamado via API e executar a tarefa.
Por favor, avise-me se você tiver alguma sugestão ou acréscimo.
👉 Siga André Bernardes no Linkedin. Clique aqui e contate-me via What's App.
Série de Livros nut Project
