---
title: Extensão Baseada em API
slug: extensao-baseada-em-api
createdAt: 2024-09-02T18:28:40.322Z
---

Os desenvolvedores podem estender as capacidades dos módulos através do módulo de extensão de API. Atualmente, as extensões de módulo suportadas incluem:

- moderation
- external\_data\_tool

Antes de estender as capacidades do módulo, prepare uma API e uma chave de API (API Key) para autenticação, que também pode ser gerada automaticamente pelo Paragraph. Além de desenvolver as capacidades correspondentes do módulo, siga as especificações abaixo para que o Paragraph possa invocar a API corretamente.

![](https://api.archbee.com/api/optimize/NB-ulyH02IT7Ep_VosDsd/k4L57rskEn3kFg85DKTQa_captura-de-tela-2024-09-03-as-91734-am.png)

## Especificações da API

O Paragraph invocará sua API de acordo com as seguintes especificações:

:::BlockQuote
POST {Seu-Endpoint-API}
:::

### Header

| Cabeçalho     | Valor                  | Descrição                                                                                                                                                          |
| ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Content-Type  | application/json       | O conteúdo da requisição está em formato JSON.                                                                                                                     |
| Authorization | Bearer {api\_key} | A chave de API é transmitida como um token. Você precisa analisar o api\_key e verificar se corresponde à chave de API fornecida para garantir a segurança da API. |

### Corpo da Requisição

:::CodeblockTabs
json

```json
{
    "point": "string",  // Ponto de extensão, diferentes módulos podem conter vários pontos de extensão
    "params": {
        ...  // Parâmetros passados para o ponto de extensão de cada módulo
    }
}
```
:::

### Resposta da API

:::CodeblockTabs
json

```json
{
    ...  // Para o conteúdo retornado pela API, consulte as especificações de design do módulo específico para diferentes pontos de extensão.
}
```
:::

## Verificação

Ao configurar a Extensão de API no Paragraph, o Paragraph enviará uma solicitação ao Endpoint da API para verificar a disponibilidade da API. Quando o Endpoint da API receber point=ping, a API deve retornar result=pong, conforme o exemplo a seguir:

### Header

:::BlockQuote
Content-Type: application/json
Authorization: Bearer {api\_key}
:::

### Corpo da Requisição

:::CodeblockTabs
json

```json
{
    "point": "ping"
}
```
:::

### Resposta Esperada da API

:::CodeblockTabs
json

```json
{
    "result": "pong"
}
```
:::

**Exemplo**

Aqui, tomamos a ferramenta de dados externos como exemplo, onde o cenário é recuperar informações meteorológicas externas com base na região como contexto.

## Especificações da API

:::BlockQuote
POST https\://fake-domain.com/api/paragraph/receive
:::

### Header

:::BlockQuote
Content-Type: application/json
Authorization: Bearer 123456
:::

### Corpo da Requisição

:::CodeblockTabs
json

```json
{
    "point": "app.external_data_tool.query",
    "params": {
        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
        "tool_variable": "weather_retrieve",
        "inputs": {
            "location": "London"
        },
        "query": "Como está o tempo hoje?"
    }
}
```
:::

### Resposta da API

:::CodeblockTabs
json

```json
{
    "result": "Cidade: Londres\nTemperatura: 10°C\nSensação Térmica®: 8°C\nQualidade do Ar: Ruim\nDireção do Vento: ENE\nVelocidade do Vento: 8 km/h\nRajadas de Vento: 14 km/h\nPrecipitação: Chuva leve"
}
```
:::

### Demonstração de Código

O código é baseado no framework Python FastAPI.

## Instalar dependências

:::CodeblockTabs
bash

```yaml
pip install 'fastapi[all]' uvicorn
```
:::

**Escrever código de acordo com as especificações da interface**

:::CodeblockTabs
python

```python
from fastapi import FastAPI, Body, HTTPException, Header
from pydantic import BaseModel

app = FastAPI()

class InputData(BaseModel):
    point: str
    params: dict

@app.post("/api/paragraph/receive")
async def paragraph_receive(data: InputData = Body(...), authorization: str = Header(None)):
    """
    Receber dados de consulta de API do Paragraph.
    """
    expected_api_key = "123456"  # TODO Sua chave de API desta API
    auth_scheme, _, api_key = authorization.partition(' ')

    if auth_scheme.lower() != "bearer" or api_key != expected_api_key:
        raise HTTPException(status_code=401, detail="Não autorizado")

    point = data.point

    # para depuração
    print(f"point: {point}")

    if point == "ping":
        return {
            "result": "pong"
        }
    if point == "app.external_data_tool.query":
        return handle_app_external_data_tool_query(params=data.params)
    # elif point == "{nome do ponto}":
        # TODO implementação de outros pontos aqui

    raise HTTPException(status_code=400, detail="Não implementado")

def handle_app_external_data_tool_query(params: dict):
    app_id = params.get("app_id")
    tool_variable = params.get("tool_variable")
    inputs = params.get("inputs")
    query = params.get("query")

    # para depuração
    print(f"app_id: {app_id}")
    print(f"tool_variable: {tool_variable}")
    print(f"inputs: {inputs}")
    print(f"query: {query}")

    # TODO sua implementação de consulta à ferramenta de dados externos aqui,
    # a resposta deve ser um dict com a chave "result", e o valor é o resultado da consulta
    if inputs.get("location") == "London":
        return {
            "result": "Cidade: Londres\nTemperatura: 10°C\nSensação Térmica®: 8°C\nQualidade do Ar: Ruim\nDireção do Vento: ENE\nVelocidade do Vento: 8 km/h\nRajadas de Vento: 14 km/h\nPrecipitação: Chuva leve"
        }
    else:
        return {"result": "Cidade desconhecida"}
```
:::

## Iniciar o serviço da API

A porta padrão é 8000. O endereço completo da API é: http\://127.0.0.1:8000/api/paragraph/receive com a chave de API configurada 123456.


:::BlockQuote
uvicorn main\:app --reload --host 0.0.0.0
:::

## Configurar esta API no Paragraph

![](https://api.archbee.com/api/optimize/NB-ulyH02IT7Ep_VosDsd/cfQjCoAxEpwpEMkQOHLbo_captura-de-tela-2024-09-03-as-91844-am.png)

Selecione esta extensão de API no App.

Ao depurar o App, o Paragraph solicitará a API configurada e enviará o seguinte conteúdo (exemplo):



:::CodeblockTabs
json

```json
{
    "point": "app.external_data_tool.query",
    "params": {
        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
        "tool_variable": "weather_retrieve",
        "inputs": {
            "location": "London"
        },
        "query": "Como está o tempo hoje?"
    }
}
```
:::

### Resposta da API:

:::CodeblockTabs
json

```json
{
    "result": "Cidade: Londres\nTemperatura: 10°C\nSensação Térmica®: 8°C\nQualidade do Ar: Ruim\nDireção do Vento: ENE\nVelocidade do Vento: 8 km/h\nRajadas de Vento: 14 km/h\nPrecipitação: Chuva leve"
}

```
:::

## Local debugging

Como a versão em nuvem do Paragraph não pode acessar serviços de API em rede interna, você pode usar o Ngrok para expor o endpoint do serviço de API local para a internet pública para depuração de código local baseada na nuvem. Os passos são:

1.Visite o site oficial do Ngrok em [https://ngrok.com](https://ngrok.com), registre-se e baixe o arquivo Ngrok.

![](https://api.archbee.com/api/optimize/NB-ulyH02IT7Ep_VosDsd/FT8frk5v2-uws_cXDWCuu_captura-de-tela-2024-09-03-as-92126-am.png)

2.Após o download, vá para o diretório de download. Descompacte o pacote e execute o script de inicialização conforme as instruções:

:::CodeblockTabs
bash

```yaml
$ unzip /caminho/para/ngrok.zip
$ ./ngrok config add-authtoken seuToken
```
:::

3.Verifique a porta do serviço de API local.

![](https://api.archbee.com/api/optimize/NB-ulyH02IT7Ep_VosDsd/2gwgbolVDK7jL1Yp5NoYh_captura-de-tela-2024-09-03-as-92401-am.png)

Execute o seguinte comando para iniciar:

:::CodeblockTabs
bash

```yaml
 $ ./ngrok http [número da porta]
```
:::

Após a inicialização bem-sucedida, você verá algo semelhante ao seguinte:

![](https://api.archbee.com/api/optimize/NB-ulyH02IT7Ep_VosDsd/RdHx8-WrhZ0AI4dIBE_vL_captura-de-tela-2024-09-02-as-33350-pm.png)

Encontre o endereço 'Forwarding', como o domínio de exemplo `https://177e-159-223-41-52.ngrok-free.app`, e use-o como seu domínio público.

Por exemplo, para expor seu serviço em execução localmente, substitua a URL de exemplo `http://127.0.0.1:8000/api/paragraph/receive` por `https://177e-159-223-41-52.ngrok-free.app/api/paragraph/receive`.

Agora, este endpoint da API está acessível publicamente. Você pode configurar este endpoint no Paragraph para depuração local. Para os passos de configuração, consulte a documentação ou guia apropriado.

## Implantar a extensão da API com Cloudflare Workers

Recomendamos que você use o Cloudflare Workers para implantar sua extensão de API, pois o Cloudflare Workers pode fornecer facilmente um endereço público e pode ser usado gratuitamente.