Todos os produtos
Search

Este produto

    Server Load Balancer:CreateListener

    Central de documentação

    Server Load Balancer:CreateListener

    Última atualização: Jun 28, 2026

    Cria um listener.

    Descrição da operação

    A operação CreateListener é uma operação assíncrona. Uma solicitação bem-sucedida retorna um ID de solicitação, mas o listener é criado em segundo plano. Chame GetListenerAttribute para consultar o status de criação do listener:

    • O estado Provisioning indica que o listener está sendo criado.

    • O estado Running indica que o listener foi criado com sucesso.

    Experimente agora

    Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

    Testar

    Autorização RAM

    A tabela abaixo descreve a autorização necessária para chamar esta API. Você pode defini-la em uma política do Resource Access Management (RAM). As colunas da tabela estão detalhadas abaixo:

    • Ação: As ações que podem ser usadas no elemento Action das instruções de política de permissão do RAM para conceder permissões para executar a operação.

    • API: A API que você pode chamar para executar a ação.

    • Nível de acesso: O nível de acesso predefinido concedido para cada API. Valores válidos: create, list, get, update e delete.

    • Tipo de recurso: O tipo de recurso que suporta autorização para executar a ação. Indica se a ação suporta permissão em nível de recurso. O recurso especificado deve ser compatível com a ação. Caso contrário, a política será ineficaz.

      • Para APIs com permissões em nível de recurso, os tipos de recursos obrigatórios são marcados com um asterisco (*). Especifique o Nome de Recurso Alibaba Cloud (ARN) correspondente no elemento Resource da política.

      • Para APIs sem permissões em nível de recurso, é exibido como Todos os Recursos. Use um asterisco (*) no elemento Resource da política.

    • Chave de condição: As chaves de condição definidas pelo serviço. A chave permite controle granular, aplicando-se somente a ações ou a ações associadas a recursos específicos. Além das chaves de condição específicas do serviço, o Alibaba Cloud fornece um conjunto de chaves de condição comuns aplicáveis a todos os serviços compatíveis com RAM.

    • Ação dependente: As ações dependentes necessárias para executar a ação. Para concluir a ação, o usuário RAM ou a função RAM deve ter permissões para executar todas as ações dependentes.

    Ação

    Nível de acesso

    Tipo de recurso

    Chave de condição

    Ação dependente

    alb:CreateListener

    create

    *LoadBalancer

    acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}

    *SecurityPolicy

    acs:alb:{#regionId}:{#accountId}:securitypolicy/{#securitypolicyId}

    *ServerGroup

    acs:alb:{#regionId}:{#accountId}:servergroup/{#servergroupId}
    • alb:ListenerProtocol
    		 Nenhuma

    Parâmetros da solicitação

    Parâmetro

    Tipo

    Obrigatório

    Descrição

    Exemplo
    LoadBalancerId

    string

    Sim

    O ID da instância do Application Load Balancer (ALB).

    alb-n5qw04uq8vavfe****
    ClientToken

    string

    Não

    Um token gerado pelo cliente usado para garantir a idempotência da solicitação. O token deve ser exclusivo entre diferentes solicitações e pode conter apenas caracteres ASCII.

    Nota

    Se você não especificar este parâmetro, o sistema usa automaticamente o RequestId da solicitação de API como o ClientToken. O RequestId é exclusivo para cada solicitação de API.

    123e4567-e89b-12d3-a456-426655440000
    DryRun

    boolean

    Não

    Especifica se deve ser realizado um dry run. Valores válidos:

    • true: Realiza um dry run para verificar possíveis problemas na solicitação, incluindo parâmetros obrigatórios, formato da solicitação e limites do serviço. O listener não é criado. Se a solicitação falhar na verificação, o sistema retorna um erro. Se a solicitação passar na verificação, o sistema retorna o código de erro DryRunOperation.

    • false (padrão): Envia a solicitação. Se a solicitação passar na verificação, o sistema executa a operação e retorna um código de status HTTP 2xx.

    false
    ListenerProtocol

    string

    Sim

    O protocolo do listener.

    Valores válidos: HTTP, HTTPS e QUIC.

    HTTP
    ListenerPort

    integer

    Sim

    A porta frontend usada pelo listener.

    Valores válidos: 1 a 65535.

    80
    ListenerDescription

    string

    Não

    Um nome personalizado para o listener.

    O nome deve ter de 2 a 256 caracteres e pode conter letras, dígitos, hifens (-), barras (/), pontos (.), underscores (_) e caracteres chineses.

    HTTP_80
    RequestTimeout

    integer

    Não

    O tempo limite da solicitação em segundos.

    Valores válidos: 1 a 600.

    Valor padrão: 60.

    Se um servidor backend não responder dentro do período de tempo limite, o load balancer retorna um erro HTTP 504 ao cliente.

    Nota

    Você pode solicitar um aumento de cota para um máximo de 3.600 segundos.

    60
    IdleTimeout

    integer

    Não

    O tempo limite de inatividade em segundos.

    Valores válidos: 1 a 600.

    Valor padrão: 15.

    Se nenhuma solicitação for recebida em uma conexão dentro do tempo limite de inatividade, o load balancer fecha a conexão. Uma nova conexão é estabelecida para a próxima solicitação.

    Nota

    Você pode solicitar um aumento de cota para um máximo de 3.600 segundos.

    3
    GzipEnabled

    boolean

    Não

    Especifica se a compressão Gzip deve ser ativada para comprimir tipos específicos de arquivos. Valores válidos:

    • true (padrão): Ativa a compressão Gzip.

    • false: Desativa a compressão Gzip.

    true
    Http2Enabled

    boolean

    Não

    Especifica se o HTTP/2 deve ser ativado. Valores válidos:

    • true (padrão): Ativa o HTTP/2.

    • false: Desativa o HTTP/2.

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    true
    SecurityPolicyId

    string

    Não

    O ID da política de segurança. Políticas de segurança do sistema e personalizadas são suportadas.

    Valor padrão: tls_cipher_policy_1_0 (uma política de segurança do sistema).

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    tls_cipher_policy_1_0
    CaEnabled

    boolean

    Não

    Especifica se a autenticação mútua deve ser ativada. Valores válidos:

    • true: Ativa a autenticação mútua.

    • false (padrão): Desativa a autenticação mútua.

    false
    XForwardedForConfig

    object

    Não

    A configuração dos cabeçalhos X-Forwarded-*.

    XForwardedForClientCertClientVerifyAlias

    string

    Não

    O nome do cabeçalho personalizado. Este parâmetro entra em vigor somente quando XForwardedForClientCertClientVerifyEnabled está definido como true.

    O nome deve ter de 1 a 40 caracteres e pode conter letras minúsculas, dígitos, hifens (-) e underscores (_).

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    test_client-verify-alias_123456
    XForwardedForClientCertClientVerifyEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-Client-Cert-Client-Verify deve ser usado para recuperar o resultado da verificação do certificado do cliente. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    true
    XForwardedForClientCertFingerprintAlias

    string

    Não

    O nome do cabeçalho personalizado. Este parâmetro entra em vigor somente quando XForwardedForClientCertFingerprintEnabled está definido como true.

    O nome deve ter de 1 a 40 caracteres e pode conter letras minúsculas, dígitos, hifens (-) e underscores (_).

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    test_finger-print-alias_123456
    XForwardedForClientCertFingerprintEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-Client-Cert-Fingerprint deve ser usado para recuperar a impressão digital do certificado do cliente. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    true
    XForwardedForClientCertIssuerDNAlias

    string

    Não

    O nome do cabeçalho personalizado. Este parâmetro entra em vigor somente quando XForwardedForClientCertIssuerDNEnabled está definido como true.

    O nome deve ter de 1 a 40 caracteres e pode conter letras minúsculas, dígitos, hifens (-) e underscores (_).

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    test_issue-dn-alias_123456
    XForwardedForClientCertIssuerDNEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-Client-Cert-Issuer-DN deve ser usado para recuperar informações sobre o emissor do certificado do cliente. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    true
    XForwardedForClientCertSubjectDNAlias

    string

    Não

    O nome do cabeçalho personalizado. Este parâmetro entra em vigor somente quando XForwardedForClientCertSubjectDNEnabled está definido como true.

    O nome deve ter de 1 a 40 caracteres e pode conter letras minúsculas, dígitos, hifens (-) e underscores (_).

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    test_subject-dn-alias_123456
    XForwardedForClientCertSubjectDNEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-Client-Cert-Subject-DN deve ser usado para recuperar informações sobre o proprietário do certificado do cliente. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    true
    XForwardedForClientSrcPortEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-Client-Srcport deve ser usado para recuperar a porta de origem do cliente. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível para listeners HTTP e HTTPS.

    true
    XForwardedForEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-For deve ser usado para recuperar o endereço IP do cliente. Valores válidos:

    • true (padrão): Ativa este recurso.

    • false: Desativa este recurso.

    Nota

    1. Se você definir este parâmetro como true, o valor padrão de XForwardedForProcessingMode será append. Você pode alterar o valor para remove.

    2. Se você definir este parâmetro como false, o ALB mantém o cabeçalho X-Forwarded-For e não realiza processamento adicional antes de enviar a solicitação a um servidor backend.

    3. Este parâmetro está disponível para listeners HTTP e HTTPS.

    true
    XForwardedForProcessingMode

    string

    Não

    O modo usado para processar o cabeçalho X-Forwarded-For. Este parâmetro entra em vigor somente quando XForwardedForEnabled está definido como true. Valores válidos:

    • append (padrão): Adiciona o endereço IP do último salto ao cabeçalho X-Forwarded-For.

    • remove: Exclui o cabeçalho X-Forwarded-For.

    Nota

    1. Se você definir o valor como append, o ALB adiciona o endereço IP do último salto ao cabeçalho X-Forwarded-For antes de enviar uma solicitação a um servidor backend.

    2. Se você definir o valor como remove, o ALB exclui o cabeçalho X-Forwarded-For antes de enviar uma solicitação a um servidor backend, independentemente de a solicitação conter um cabeçalho X-Forwarded-For.

    3. Este parâmetro está disponível para listeners HTTP e HTTPS.

    append
    XForwardedForProtoEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-Proto deve ser usado para recuperar o protocolo do listener da instância ALB. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível para listeners HTTP, HTTPS e QUIC.

    false
    XForwardedForSLBIdEnabled

    boolean

    Não

    Especifica se o cabeçalho SLB-ID deve ser usado para recuperar o ID da instância ALB. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível para listeners HTTP, HTTPS e QUIC.

    false
    XForwardedForSLBPortEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-Port deve ser usado para recuperar a porta do listener da instância ALB. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível para listeners HTTP, HTTPS e QUIC.

    false
    XForwardedForClientSourceIpsEnabled

    boolean

    Não

    Especifica se o ALB deve recuperar o endereço IP do cliente a partir do cabeçalho X-Forwarded-For. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível para listeners HTTP e HTTPS.

    false
    XForwardedForClientSourceIpsTrusted

    string

    Não

    Especifica os endereços IP de proxy confiáveis.

    O ALB percorre o cabeçalho X-Forwarded-For da direita para a esquerda, selecionando o primeiro endereço IP que não está nesta lista de confiança como o endereço IP do cliente. Este IP é então usado para recursos como limitação baseada em IP de origem.

    10.1.1.0/24
    XForwardedForHostEnabled

    boolean

    Não

    Especifica se o cabeçalho X-Forwarded-Host deve ser usado para recuperar o nome de domínio usado para acessar a instância ALB. Valores válidos:

    • true: Ativa este recurso.

    • false (padrão): Desativa este recurso.

    Nota

    Este parâmetro está disponível para listeners HTTP, HTTPS e QUIC.

    false
    QuicConfig

    object

    Não

    A configuração do listener QUIC associado.

    QuicListenerId

    string

    Não

    O ID do listener QUIC a ser associado ao listener. Este parâmetro é obrigatório para listeners HTTPS quando QuicUpgradeEnabled está definido como true.

    Nota

    O listener HTTPS e o listener QUIC associado devem pertencer à mesma instância ALB, e o listener QUIC não deve estar já associado a outro listener.

    lsn-o4u54y73wq7b******
    QuicUpgradeEnabled

    boolean

    Não

    Especifica se o upgrade QUIC deve ser ativado. Valores válidos:

    • true: Ativa o upgrade QUIC.

    • false (padrão): Desativa o upgrade QUIC.

    Nota

    Este parâmetro está disponível apenas para listeners HTTPS.

    false
    Certificates

    array<object>

    Não

    Uma lista de certificados de servidor.

    object

    Não

    O certificado.

    CertificateId

    string

    Não

    O ID do certificado de servidor padrão. Apenas um certificado de servidor padrão é suportado.

    Nota

    • Este parâmetro é obrigatório se ListenerProtocol estiver definido como HTTPS ou QUIC.

    • Para associar certificados adicionais, chame a operação AssociateAdditionalCertificatesWithListener após a criação do listener.

    103705*******
    CaCertificates

    array<object>

    Não

    Uma lista de certificados CA para o listener. Apenas um certificado CA é suportado.

    object

    Não

    O certificado CA.

    CertificateId

    string

    Não

    O ID do certificado CA.

    Nota

    Este parâmetro é obrigatório se CaEnabled estiver definido como true.

    123157*******
    DefaultActions

    array<object>

    Sim

    As ações padrão para o listener.

    array<object>

    Sim

    A lista de ações padrão.

    ForwardGroupConfig

    object

    Sim

    A configuração da ação de encaminhamento. Você pode especificar até 20 ações de encaminhamento.

    ServerGroupTuples

    array<object>

    Sim

    Os grupos de servidores de destino.

    object

    Sim

    Os grupos de servidores de destino.

    ServerGroupId

    string

    Sim

    The ID of the destination server group.

    sgp-8ilqs4axp6******
    Type

    string

    Sim

    O tipo de ação.

    Defina como ForwardGroup para encaminhar solicitações a um ou mais grupos de servidores.

    ForwardGroup
    Tag

    array<object>

    Não

    Uma lista de tags a serem adicionadas ao listener.

    object

    Não

    A tag.

    Key

    string

    Não

    A chave da tag. A chave pode ter até 128 caracteres e não pode começar com aliyun ou acs:, nem conter http:// ou https://.

    env
    Value

    string

    Não

    O valor da tag. O valor pode ter até 128 caracteres e não pode começar com aliyun ou acs:, nem conter http:// ou https://.

    product

    Elementos de resposta

    Elemento

    Tipo

    Descrição

    Exemplo

    object

    Detalhes do listener criado.

    JobId

    string

    O ID da tarefa assíncrona.

    72dcd26b-f12d-4c27-b3af-18f6aed5****
    ListenerId

    string

    O ID do listener.

    lsn-o4u54y73wq7b******
    RequestId

    string

    O ID da solicitação.

    CEF72CEB-54B6-4AE8-B225-F876*******

    Exemplos

    Resposta de sucesso

    JSON formato

    {
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "ListenerId": "lsn-o4u54y73wq7b******",
  "RequestId": "CEF72CEB-54B6-4AE8-B225-F876*******"
}

    Códigos de erro

    Código de status HTTP

    Código de erro

    Mensagem de erro

    Descrição
    400 ResourceAlreadyExist.Listener The specified resource %s is already exist.
    400 IncorrectStatus.LoadBalancer The status of %s [%s] is incorrect.
    400 IncorrectBusinessStatus.LoadBalancer The business status of %s [%s]  is incorrect. The business status of %s [%s]  is incorrect.
    400 ResourceQuotaExceeded.LoadBalancerListenersNum The quota of %s is exceeded for resource %s, usage %s/%s. The quota of %s is exceeded for resource %s, usage %s/%s.
    400 OperationDenied.CrossLoadBalancerQUICListener The operation is not allowed because of %s. The operation is not allowed because of %s.
    400 ResourceAlreadyAssociated.Listener The specified resource %s is already associated. The specified resource %s is already associated.
    400 ResourceQuotaExceeded.SecurityPolicyAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. The quota of %s is exceeded for resource %s. Usage: %s/%s.
    400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s.
    400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s.
    400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s.
    400 Mismatch.VpcId The %s is mismatched for %s and %s. The %s is mismatched for %s and %s.
    400 OperationDenied.ServerGroupProtocolNotSupport The operation is not allowed because of ServerGroupProtocolNotSupport. The operation is not allowed because the server group protocol is not supported.
    400 OperationDenied.GRPCServerGroup The operation is not allowed because of %s.
    400 Mismatch.LoadBalancerEditionAndConnectionDrain The %s and %s are mismatched. The %s and %s are mismatched.
    400 Mismatch.LoadBalancerEditionAndSlowStartEnable The %s and %s are mismatched. The %s and %s are mismatched.
    400 InvalidParameter Invalid parameter, please check the parameter input. Invalid parameter, please check the parameter input.
    400 OperationDenied.CACertificateCorrupted The CA certificate is corrupted. CA certificate is corrupted
    403 Forbidden.SecurityPolicy Authentication has failed for SecurityPolicy.
    403 Forbidden.LoadBalancer Authentication is failed for %s. Authentication is failed for %s.
    403 Forbidden.Listener Authentication is failed for %s. Authentication is failed for %s.
    404 ResourceNotFound.LoadBalancer The specified resource %s is not found. The specified resource %s is not found.
    404 ResourceNotFound.ServerGroup The specified resource %s is not found.
    404 ResourceNotFound.SecurityPolicy The specified resource %s is not found. The specified resource %s is not found.
    404 ResourceNotFound.Listener The specified resource %s is not found.
    404 ResourceNotFound.Certificate The specified resource %s is not found. The specified resource %s is not found.

    Consulte Códigos de Erro para uma lista completa.

    Notas de versão

    Consulte Notas de Versão para uma lista completa.