# Configurações de connector Um [connector](/pt-br/documentacao/plataforma/connectors/) é o objeto que guarda onde e como uma aplicação alcança uma origem, o servidor que guarda o seu conteúdo. O tipo dele, `http`, `storage` ou `live_ingest`, define quais configurações o connector carrega. Azion Console e Azion API escrevem o mesmo objeto, então cada tabela desta página nomeia o rótulo do Console ao lado do campo da API. Os campos da API aparecem como caminhos dentro do corpo da requisição, como `attributes.connection_options.host`. --- ## Objeto connector O corpo JSON abaixo é um connector completo do tipo `http` com um endereço. Todas as opções de conexão estão no padrão, exceto `transport_policy` e `host`, e [Load Balancer](/pt-br/documentacao/plataforma/connectors/#load-balancer) e [Origin Shield](/pt-br/documentacao/plataforma/connectors/#origin-shield) estão desativados: ```json { "name": "my-connector", "active": true, "type": "http", "attributes": { "addresses": [ { "address": "origin.example.com", "http_port": 80, "https_port": 443, "active": true } ], "connection_options": { "dns_resolution": "both", "transport_policy": "force_https", "http_version_policy": "http1_1", "host": "origin.example.com", "path_prefix": "", "following_redirect": false, "real_ip_header": "X-Real-IP", "real_port_header": "X-Real-PORT" }, "modules": { "load_balancer": { "enabled": false }, "origin_shield": { "enabled": false } } } } ``` O caminho da API é `/v4/workspace/connectors`, e o de um connector é `/v4/workspace/connectors/{connector_id}`. Um `POST` que cria um connector responde `202` com `"state": "pending"` e o objeto completo, padrões incluídos. Um `PATCH` mescla as chaves que você envia no objeto armazenado. Um `PUT` o substitui: um `PUT` sem `connection_options` redefine cada opção de conexão para o seu padrão. Para cada operação, consulte [Azion API](https://api.azion.com/). Azion CLI recebe o mesmo corpo JSON de um arquivo: `azion create connector --type http --file my-connector.json` imprime `Created Connector with ID `. Uma alteração em um connector entra em vigor sem um novo deployment. Ela chega à infraestrutura distribuída da Azion em vários minutos, e os data centers a aplicam em momentos diferentes. Uma aplicação envia requisições a um connector por meio de uma regra com o behavior `Set Connector`. Para escrever essa regra, consulte [Rules Engine para Applications](/pt-br/documentacao/plataforma/applications/rules-engine/). --- ## Geral Os campos gerais nomeiam o connector e definem o seu tipo. A API exige `name`, `type` e `attributes` em todo connector. | Console | Campo da API | Tipo | Padrão | Descrição | | ------------------------------------------------------------------------- | ------------ | ------- | ------ | ----------------------------------------------------------------------------------------- | | **Name** | `name` | string | nenhum | Obrigatório. 1 a 255 caracteres. | | **Connector Type**, com os cards *HTTP*, *Object Storage* e *Live Ingest* | `type` | enum | nenhum | Obrigatório. `http`, `storage` ou `live_ingest`. Define quais campos `attributes` aceita. | | nenhum | `active` | boolean | `true` | `true` ou `false`. | Um connector do tipo `http` aceita os campos de Endereços, Opções de conexão, Load Balancer e Origin Shield. Um connector do tipo `storage` aceita os campos de Storage, e um connector do tipo `live_ingest` aceita o campo de Live Ingest. --- ## Endereços Os endereços de um connector do tipo `http` são os servidores de origem aos quais ele se conecta. Cada item de `attributes.addresses` contém um endereço com suas portas, seu estado e sua função no balanceamento de carga. A seção **Address Management** do Console os escreve. | Console | Campo da API | Tipo | Padrão | Descrição | | ----------------------------------------- | ---------------------------------------------------------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------------- | | **Address** | `attributes.addresses[].address` | string | nenhum | Obrigatório. Um endereço IPv4, um endereço IPv6 ou um hostname, de até 255 caracteres, sem protocolo e sem porta. | | **HTTP Port** | `attributes.addresses[].http_port` | integer | `80` | 1 a 65535. A porta das conexões HTTP com este endereço. | | **HTTPS Port** | `attributes.addresses[].https_port` | integer | `443` | 1 a 65535. A porta das conexões HTTPS com este endereço. | | **Active** | `attributes.addresses[].active` | boolean | `true` | `false` tira o endereço da rotação. | | **Server Role**, com *Primary* e *Backup* | `attributes.addresses[].modules.load_balancer.server_role` | enum | `primary` | `primary` ou `backup`. A função do endereço no balanceamento de carga. | | **Weight** | `attributes.addresses[].modules.load_balancer.weight` | integer | `1` | 1 a 100. Pesos maiores destinam mais tráfego a este endereço. | Um connector contém um endereço, a menos que Load Balancer esteja ativado. Dois endereços com Load Balancer desativado são recusados com `28004`. Com Load Balancer ativado, um connector contém até 15 endereços, e um 16º é recusado com `28011`. Para todos os limites em um só lugar, consulte [Limites de Connectors](/pt-br/documentacao/plataforma/connectors/limites/). Um endereço com protocolo ou porta, como `https://origin.example.com` ou `origin.example.com:443`, é recusado com `28001`. Azion Console mostra `Address must be a valid IPv4, IPv6, or hostname, without protocol or port.` Defina as portas em **HTTP Port** e **HTTPS Port**, e um caminho em `path_prefix`. Um endereço retorna `"modules": null` na leitura até que você envie os campos de Load Balancer dele. Um endereço enviado apenas com `weight` retorna `server_role` como `primary`, e um enviado apenas com `server_role` retorna `weight` como `1`. Um endereço `backup` é recusado no método *IP Hash* com `28005`. Azion Console mostra `Backup role is not available when the load balancing method is IP Hash.` e `Backup role is not supported with IP Hash. Change this address to Primary or select another method.` Um peso fora do intervalo mostra `Weight must be between 1 and 100` no Console. --- ## Opções de conexão As opções de conexão de um connector do tipo `http` definem como o connector se comunica com seus endereços: o header `Host`, o caminho, o protocolo, a versão de IP e os headers que levam o endereço do cliente. Elas ficam em `attributes.connection_options`. | Console | Campo da API | Tipo | Padrão | Descrição | | --------------------------------------------------------------------------- | --------------------------------------------------- | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Host** | `attributes.connection_options.host` | string | `${host}` | 1 a 255 caracteres. O header `Host` enviado à origem. `${host}` envia o host que o cliente requisitou, e um valor literal é enviado como está. Um valor vazio é recusado com `10018`. | | **Path** | `attributes.connection_options.path_prefix` | string | `""`, sem prefixo | Até 255 caracteres, começando com `/`. Adicionado antes do caminho da requisição. Um valor sem a barra inicial é recusado com `28009`. | | **Transport Protocol Policy**, com *Preserve*, *Force HTTPS* e *Force HTTP* | `attributes.connection_options.transport_policy` | enum | `preserve` | `preserve` mantém o esquema que o cliente usou. `force_https` se conecta à origem apenas por HTTPS, e `force_http` apenas por HTTP. | | **DNS Resolution Policy**, com *IPv4 and IPv6* e *Force IPv4* | `attributes.connection_options.dns_resolution` | enum | `both` | `both` se conecta por IPv4 ou IPv6. `force_ipv4` se conecta apenas por IPv4. | | nenhum | `attributes.connection_options.http_version_policy` | enum | `http1_1` | A versão de HTTP até a origem. `http1_1`, HTTP/1.1, é o único valor. | | **Following Redirect** | `attributes.connection_options.following_redirect` | boolean | `false` | `true` segue os redirecionamentos HTTP que a origem retorna. | | **Real IP Header** | `attributes.connection_options.real_ip_header` | string | `X-Real-IP` | 1 a 100 caracteres. O nome do header que leva o endereço IP do cliente até a origem. | | **Real Port Header** | `attributes.connection_options.real_port_header` | string | `X-Real-PORT` | 1 a 100 caracteres. O nome do header que leva a porta do cliente até a origem. | O valor de `host` decide qual nome a origem vê. Por exemplo, com o padrão `${host}`, um cliente que requisita `www.example.com` faz o connector enviar `Host: www.example.com`. Com `"host": "origin.example.com"`, o connector envia `Host: origin.example.com` em toda requisição. Uma origem que roteia requisições por nome pode não responder ao host do cliente, então envie o nome da própria origem como valor literal. Azion Console valida **Host** com `Host must be a valid hostname, IP address, or variable.` O valor de `path_prefix` vai na frente do caminho que o cliente requisitou. Com `/anything`, uma requisição para `/get` chega à origem como `/anything/get`. Para **Path**, Azion Console diz "Use '/' for the root path." e valida o campo com `Path must start with a forward slash (/)`. Por padrão, a origem recebe o endereço IP do cliente em `X-Real-IP` e a porta do cliente em `X-Real-PORT`. Renomear `real_ip_header` altera o nome do header: com `X-Client-Real-IP`, a origem recebe `X-Client-Real-IP` e nenhum `X-Real-IP`. Algumas origens descartam `X-Real-IP` por conta própria. Para adicionar o IP do cliente a um header com uma regra, consulte [Envie o IP do cliente para a origem em um header](/pt-br/documentacao/suporte/ip-original-header/). --- ## Load Balancer Load Balancer distribui requisições entre os endereços de um connector do tipo `http`. No Console, o switch **Load Balancer** da seção **Modules** o ativa, e os campos **Method**, **Max Retries**, **Connection Timeout** e **Read/Write Timeout** aparecem. Na API, os campos ficam em `attributes.modules.load_balancer`. | Console | Campo da API | Tipo | Padrão | Descrição | | -------------------------------------------------------------- | ------------------------------------------------------------ | ----------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Load Balancer** | `attributes.modules.load_balancer.enabled` | boolean | `false` | `true` ativa Load Balancer no connector e permite até 15 endereços. | | **Method**, com *Round Robin*, *Least Connections* e *IP Hash* | `attributes.modules.load_balancer.config.method` | enum | `round_robin` | `round_robin`, `least_conn` ou `ip_hash`. `ip_hash` recusa endereços `backup`. | | **Max Retries** | `attributes.modules.load_balancer.config.max_retries` | integer | `0` na API, `3` no Console | 0 a 20. O número de novas tentativas em uma falha de conexão. | | **Connection Timeout** | `attributes.modules.load_balancer.config.connection_timeout` | integer, segundos | `60` segundos na API, `30` segundos no Console | 1 a 300 segundos. O tempo máximo de espera pela conexão com a origem. | | **Read/Write Timeout** | `attributes.modules.load_balancer.config.read_write_timeout` | integer, segundos | `120` segundos na API, `60` segundos no Console | 1 a 600 segundos. O tempo máximo de espera para que dados sejam lidos ou escritos na conexão aberta com a origem. | Com `enabled` definido como `true`, `config` deve conter pelo menos uma chave, ou a API recusa a requisição com `28014`. Uma chave que você deixa de fora recebe o padrão da API. Por exemplo, `"config": {"method": "round_robin"}` retorna na leitura com `max_retries` `0`, `connection_timeout` `60` e `read_write_timeout` `120`. Quando você ativa **Load Balancer** no Console, o formulário preenche *Round Robin*, `3`, `30` e `60` em vez disso. As novas tentativas e os dois timeouts existem apenas com Load Balancer ativado. Um connector sem Load Balancer não tem timeout configurável. Para os timeouts que se aplicam nesse caso, consulte [Como Connectors funciona](/pt-br/documentacao/plataforma/connectors/como-funciona/). Para saber como cada método escolhe um endereço, consulte [Métodos de balanceamento](/pt-br/documentacao/plataforma/connectors/load-balancer/metodos-de-balanceamento/). --- ## Origin Shield Origin Shield protege a origem de um connector do tipo `http` de duas formas. Origin IP ACL permite que sua origem aceite apenas os endereços publicados da Azion, e HMAC assina cada requisição que o connector envia à origem. Na API, os campos ficam em `attributes.modules.origin_shield`. | Console | Campo da API | Tipo | Padrão | Descrição | | ------------------------- | --------------------------------------------------------------------------- | ------- | ------------------ | ------------------------------------------------------------------------------------- | | **Origin Shield** | `attributes.modules.origin_shield.enabled` | boolean | `false` | `true` ativa Origin Shield no connector. | | **Origin IP ACL** | `attributes.modules.origin_shield.config.origin_ip_acl.enabled` | boolean | `false` | `true` ativa Origin IP ACL. | | **HMAC** | `attributes.modules.origin_shield.config.hmac.enabled` | boolean | `false` | `true` assina cada requisição à origem com as credenciais abaixo. | | **Type**, somente leitura | `attributes.modules.origin_shield.config.hmac.config.type` | enum | `aws4_hmac_sha256` | O esquema de assinatura. | | **Region** | `attributes.modules.origin_shield.config.hmac.config.attributes.region` | string | nenhum | Obrigatório. 1 a 255 caracteres. Uma região que o provedor de object storage suporta. | | **Service** | `attributes.modules.origin_shield.config.hmac.config.attributes.service` | string | `s3` | 1 a 255 caracteres. Obrigatório no Console. | | **Access Key** | `attributes.modules.origin_shield.config.hmac.config.attributes.access_key` | string | nenhum | Obrigatório. 1 a 255 caracteres. | | **Secret Key** | `attributes.modules.origin_shield.config.hmac.config.attributes.secret_key` | string | nenhum | Obrigatório. 1 a 255 caracteres. Azion Console o exibe como um campo de senha. | Com `enabled` definido como `true`, `config` deve conter pelo menos uma chave, e com `hmac.enabled` definido como `true`, `hmac.config` deve estar presente. Caso contrário, a API recusa a requisição com `28014`. Desativar HMAC remove as credenciais armazenadas, então você as informa de novo quando o ativa outra vez. As credenciais HMAC pertencem a uma conta no provedor de object storage que guarda o conteúdo privado. Por exemplo, um connector que lê um bucket privado pelo endpoint S3 `s3.us-east-005.azionstorage.net` envia `region` `us-east-005`, `service` `s3` e uma credencial com escopo nesse bucket. Com HMAC desativado, esse endpoint responde `401`. Para saber como Origin IP ACL e HMAC protegem a origem, consulte [Origin IP ACL e HMAC](/pt-br/documentacao/plataforma/connectors/origin-shield/origin-ip-acl-e-hmac/). --- ## Storage Um connector do tipo `storage` lê de um [bucket de Object Storage](/pt-br/documentacao/plataforma/object-storage/buckets-e-objetos/) da sua conta. Ele carrega dois atributos e nenhum endereço ou opção de conexão. | Console | Campo da API | Tipo | Padrão | Descrição | | --------------------------------------------------------------------------- | ------------------- | ------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Seletor de bucket, *Select a Bucket*, com o botão **Create Object Storage** | `attributes.bucket` | string | nenhum | Obrigatório. Até 255 caracteres. O nome de um bucket existente. Um bucket que não existe é recusado com `28007`. | | **Prefix** | `attributes.prefix` | string | `null` quando omitido | Opcional na API, obrigatório no Console. 1 a 255 caracteres, como `images/`. Filtra os objetos dentro do bucket. Uma string vazia é recusada com `10018`. | O seletor de bucket lista os buckets da sua conta, e **Create Object Storage** cria um bucket sem sair do formulário. Na API, deixe `prefix` de fora para armazenar `null`, e nunca o envie vazio. Por exemplo, este corpo cria um connector do tipo `storage` para os objetos em `images/`: ```json { "name": "my-connector", "type": "storage", "attributes": { "bucket": "my-bucket", "prefix": "images/" } } ``` --- ## Live Ingest Um connector do tipo `live_ingest` pertence a [Live Ingest](/pt-br/documentacao/plataforma/connectors/#live-ingest). Ele carrega um atributo, `region`, e nenhum endereço ou opção de conexão. | Console | Campo da API | Tipo | Padrão | Descrição | | ---------- | ------------------- | ---- | ------ | ------------------------------------------------------------------------------- | | **Region** | `attributes.region` | enum | nenhum | Obrigatório. `us-east-1`, `us-east-2`, `br-east-1`, `br-east-2` ou `br-east-3`. | Uma requisição sem `region` é recusada com `10059`, e um valor fora da lista com `10039`. Um `bucket` enviado com este tipo é aceito e não é armazenado. Por exemplo, este corpo cria um connector do tipo `live_ingest` em `br-east-1`: ```json { "name": "my-connector", "type": "live_ingest", "attributes": { "region": "br-east-1" } } ``` Para saber como Live Ingest funciona, consulte [Ingestão e entrega](/pt-br/documentacao/plataforma/connectors/live-ingest/ingestao-e-entrega/). --- ## Erros A API recusa cada requisição abaixo com HTTP `400` e não cria nem altera nada. O código e a mensagem ficam no array `errors` da resposta, com um `source.pointer` para o campo. | Código | Mensagem | Causa | O que fazer | | ------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | `28001` | `Invalid address format. Must be a valid IPv4, IPv6, or CNAME.` | Um endereço carrega um protocolo ou uma porta, como `https://origin.example.com` ou `origin.example.com:443`. | Envie apenas o hostname ou o endereço IP, e defina as portas em `http_port` e `https_port`. | | `28004` | `To use more than one address, you must enable the Load Balancer module.` | O connector tem dois ou mais endereços e Load Balancer está desativado, na criação ou quando você desativa Load Balancer. | Ative Load Balancer no connector, ou mantenha um endereço. | | `28011` | `When the Load Balancer module is enabled, you can use up to 15 addresses.` | O connector tem 16 ou mais endereços. | Mantenha 15 endereços ou menos. | | `28005` | `Backup addresses are not allowed when using 'ip_hash' as load balance method.` | Um endereço tem `server_role` `backup` e o método é `ip_hash`. | Defina o endereço como `primary`, ou escolha `round_robin` ou `least_conn`. | | `28014` | `Module configuration must be provided when 'enabled' is true.` | Load Balancer ou Origin Shield tem `enabled` `true` sem `config`, com um `config` vazio ou com `null`; ou HMAC está ativado sem `hmac.config`. | Envie `config` com pelo menos uma chave, ou `hmac.config` com as credenciais. | | `28009` | `Invalid path format. Must be a valid path.` | `path_prefix` não começa com `/`. | Comece o valor com `/`, como `/anything`. | | `28007` | `Invalid bucket name Storage Connector.` | `bucket` nomeia um bucket que não existe na conta. | Crie o bucket primeiro, ou envie o nome de um bucket existente. | | `28000` | `Cannot delete an Connector referenced by another resource. References: EdgeApplicationRuleEngine - id: ` | Um `DELETE` tem como alvo um connector para o qual uma regra ainda aponta; a mensagem nomeia a regra. | Aponte a regra para outro connector, ou exclua a regra, e então repita o `DELETE`. | | `10018` | `This field may not be blank.` | `host` ou `prefix` é uma string vazia. | Envie um valor, ou deixe `prefix` de fora. | | `10059` | `This field is required.` | Um connector do tipo `live_ingest` não tem `region`. | Envie `region` com um dos cinco valores. | | `10039` | `"preserve" is not a valid choice.` | Um campo enum contém um valor fora da sua lista; a mensagem cita o valor, como `"http2"` para `http_version_policy` ou `"eu-west-1"` para `region`. | Envie um valor da lista do campo. | | `10050` | `Ensure this value is greater than or equal to 1.` | `weight` é `0`. | Envie um peso de 1 a 100. | | `10068` | `Ensure this value is less than or equal to 100.` | Um número está acima do seu máximo; a mensagem o nomeia: `100` para `weight`, `20` para `max_retries`, `300` para `connection_timeout`, `600` para `read_write_timeout`. | Envie um valor dentro do intervalo do campo. | | `10046` | `Ensure this field has no more than 255 characters.` | `name` tem mais de 255 caracteres. | Encurte o nome para 255 caracteres ou menos. | Azion CLI imprime a mesma mensagem dentro do seu próprio erro. Para `28000`, isso é `Error: Failed to delete the Connector: [...]`. --- ## Recursos relacionados - [Como Connectors funciona](/pt-br/documentacao/plataforma/connectors/como-funciona.md): O caminho que uma requisição percorre de uma regra até o connector e sua origem, e os timeouts que se aplicam sem Load Balancer. - [Limites de Connectors](/pt-br/documentacao/plataforma/connectors/limites.md): Cada limite de um connector e dos seus endereços, com o que acontece além de cada um. - [Métodos de balanceamento](/pt-br/documentacao/plataforma/connectors/load-balancer/metodos-de-balanceamento.md): Como Round Robin, Least Connections e IP Hash escolhem um endereço, e como peso e função do servidor alteram a escolha. - [Rules Engine para Applications](/pt-br/documentacao/plataforma/applications/rules-engine.md): O behavior Set Connector, que envia as requisições de uma aplicação a um connector.