> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Atualizar um listener
Requer a ação do IAM **`loadbalancer:UpdateListener`**. Consulte [permissões de balanceadores de carga](/loadbalancer/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política.
## OpenAPI
````yaml /pt/api-reference/specs/loadbalancer.yaml patch /v1/load-balancers/{id}/listeners/{listener_id}
openapi: 3.0.3
info:
title: API do Basaltic Load Balancer
version: 1.0.0
description: >
Relações de solicitação aceitam referências classificadas por sintaxe
resolvidas dentro da conta e região do chamador. Referências IP flutuantes
aceitam somente UUID ou CRN; os alvos IP permanecem literais. Balanceadores
de carga gerenciados: ouvintes, pools de destino, verificações de
integridade e os certificados TLS que um ouvinte encerra.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://loadbalancer.{region}.basaltic.sh
description: Endpoint de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de região
security:
- BearerAuth: []
paths:
/v1/load-balancers/{id}/listeners/{listener_id}:
patch:
tags:
- Load Balancers
summary: Atualizar um listener
operationId: updateListener
parameters:
- name: id
in: path
required: true
schema:
type: string
example: 4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c
- name: listener_id
in: path
required: true
schema:
type: string
example: e1f2a3b4-c5d6-4789-e0f1-a2b3c4d5e6f7
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateListenerRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListenerResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
UpdateListenerRequest:
additionalProperties: false
type: object
description: >
Atualiza um listener. Use default_certificate para selecionar como
padrão um certificado já anexado. Certificados renovados são atualizados
automaticamente; gerencie os vínculos pela coleção de certificados do
listener.
Omita default_target_group para mantê-lo inalterado, envie uma
referência em string para substituí-lo ou envie null para removê-lo.
properties:
default_target_group:
type: string
nullable: true
minLength: 1
description: >-
UUID, CRN ou nome exato do grupo de destino no escopo da conta. Null
remove o padrão; a omissão o mantém inalterado.
example: b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4
exposure:
type: string
enum:
- public_only
- private_only
- both
example: both
description: |
Mute quais endereços são vinculados. Omitir para deixar inalterado.
tags:
$ref: '#/components/schemas/Tags'
default_certificate:
type: string
minLength: 1
description: >-
UUID, CRN ou nome exato de um certificado já vinculado a este
listener. Define-o como padrão e desmarca o padrão anterior
atomicamente. Não vincula novos certificados.
example: prod-web
ListenerResponse:
type: object
properties:
listener:
$ref: '#/components/schemas/Listener'
required:
- listener
Tags:
type: object
additionalProperties:
type: string
example:
environment: production
team: backend
Listener:
type: object
required:
- crn
- id
- protocol
- port
- exposure
- tags
- created_at
- updated_at
- default_certificate
- default_target_group
properties:
crn:
type: string
description: >-
CRN com escopo principal com nome de balanceador de carga imutável e
componentes UUID filhos.
id:
type: string
format: uuid
example: e1f2a3b4-c5d6-4789-e0f1-a2b3c4d5e6f7
protocol:
type: string
enum:
- http
- https
- tcp
- udp
example: https
port:
type: integer
minimum: 1
maximum: 65535
example: 443
exposure:
type: string
enum:
- public_only
- private_only
- both
example: both
description: >
Qual LB endereça este listener vincula. 'public_only' e 'both'
exigem que o LB carregue um IP flutuante; se o FIP for separado mais
tarde, o ouvinte é descartado até que um FIP seja re-anexado ou a
exposição seja invertida para private_only.
tags:
$ref: '#/components/schemas/Tags'
created_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
updated_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
default_certificate:
anyOf:
- $ref: '#/components/schemas/ResourceRef'
- type: object
nullable: true
enum:
- null
description: >-
Certificado padrão de um listener HTTPS, usado quando nenhum SNI
corresponde ou o cliente não envia SNI. Null quando ausente. Liste
todos os certificados vinculados pelo endpoint de certificados do
listener.
example:
id: 550e8400-e29b-41d4-a716-446655440012
crn: crn:certificate::my-account:certificate/prod-web
name: prod-web
default_target_group:
anyOf:
- $ref: '#/components/schemas/ResourceRef'
- type: object
nullable: true
enum:
- null
description: >-
Grupo de destinos usado quando nenhuma regra de roteamento
corresponde, ou null quando nenhum está configurado.
example:
id: 550e8400-e29b-41d4-a716-446655440013
crn: crn:loadbalancer:sa-saopaulo-1:my-account:target-group/web
name: web
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Código de erro identificando o tipo de erro
example: INVALID_INPUT
message:
type: string
description: Mensagem de erro legível pelo ser humano
example: Invalid request parameters
params:
type: object
additionalProperties: true
description: >-
Valores não sensíveis opcionais para interpolação de erros
localizados, codificados por código de erro. Nunca presente para
erros de servidor.
example:
instances: 2
pools: 0
request_id:
type: string
format: uuid
description: Solicitar ID para depuração
example: 550e8400-e29b-41d4-a716-446655440000
ResourceRef:
type: object
required:
- id
- crn
properties:
id:
type: string
format: uuid
example: 288aa1e9-bbf5-5584-bce9-6a688f06d8a1
crn:
type: string
example: crn:catalog::platform:country/288aa1e9-bbf5-5584-bce9-6a688f06d8a1
name:
type: string
description: >-
Rótulo no momento da resposta: o nome do recurso, quando houver, ou
seu rótulo legível (número de fatura, nome de exibição da conta).
Ausente quando o destino não existe mais. Não é uma chave de
consulta.
example: Brazil
responses:
BadRequest:
description: Parâmetros de solicitação inválidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INVALID_INPUT
message: Invalid request parameters
request_id: 550e8400-e29b-41d4-a716-446655440000
Unauthorized:
description: Autenticação necessária ou token inválido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
Forbidden:
description: Permissões insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
NotFound:
description: Página não encontrada
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: Resource not found
request_id: 550e8400-e29b-41d4-a716-446655440000
InternalServerError:
description: Erro interno do servidor
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INTERNAL_ERROR
message: An internal error occurred
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >+
Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `.
Esta é a forma recomendada de autenticação.
Obtenha o token trocando o par de chaves de acesso de uma conta de
serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`.
Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis
com OAuth podem obter e renovar o token para você.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso
também serve como credencial AWS SigV4 para o endpoint de objetos
compatível com S3, que aceita somente esse método de autenticação.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.