Externalizar URLs externalizing-urls

No AEM, o Externalizador é um serviço OSGi que permite transformar programaticamente um caminho de recurso (por exemplo, /path/to/my/page) em uma URL externa e absoluta (por exemplo, https://www.mycompany.com/path/to/my/page), prefixando o caminho com um DNS pré-configurado.

Como uma instância do AEM as a Cloud Service não pode saber seu URL visível externamente e porque, às vezes, um link precisa ser criado fora do escopo da solicitação, esse serviço fornece um local central para configurar esses URLs externos e criá-los.

Este artigo explica como configurar o serviço Externalizador e como usá-lo. Para obter detalhes técnicos do serviço, consulte Javadocs.

Comportamento padrão do externalizador e como sobrescrever default-behavior

Pronto para uso, o serviço Externalizador mapeia alguns identificadores de domínio para prefixos de URL absolutos que correspondem aos URLs de serviço do AEM gerados para o ambiente, como author https://author-p12345-e6789.adobeaemcloud.com e publish https://publish-p12345-e6789.adobeaemcloud.com. Os URLs de base para cada um desses domínios padrão são lidos das variáveis de ambiente definidas pelo Cloud Manager.

Para referência, a configuração OSGi padrão para com.day.cq.commons.impl.ExternalizerImpl.cfg.json é efetivamente:

{
   "externalizer.domains": [
      "local $[env:AEM_EXTERNALIZER_LOCAL;default=http://localhost:4502]",
      "author $[env:AEM_EXTERNALIZER_AUTHOR;default=http://localhost:4502]",
      "publish $[env:AEM_EXTERNALIZER_PUBLISH;default=http://localhost:4503]",
      "preview $[env:AEM_EXTERNALIZER_PREVIEW;default=http://localhost:4503]"
   ]
}
CAUTION
Os mapeamentos de domínio do Externalizador local, author, preview e publish padrão na configuração OSGi devem ser preservados com os valores $[env:...] originais listados acima.
Implantar um arquivo com.day.cq.commons.impl.ExternalizerImpl.cfg.json personalizado no AEM as a Cloud Service que omita qualquer um desses mapeamentos de domínio predefinidos pode resultar em um comportamento imprevisível do aplicativo.

Para substituir os valores preview e publish, use as variáveis de ambiente do Cloud Manager conforme descrito no artigo Configurar OSGi para o AEM as a Cloud Service e definir as variáveis AEM_CDN_DOMAIN_PUBLISH e AEM_CDN_DOMAIN_PREVIEW predefinidas.

Configurar o serviço externalizador configuring-the-externalizer-service

O serviço Externalizer permite definir centralmente o domínio que pode ser usado para prefixar programaticamente caminhos de recursos. O serviço Externalizer só deve ser usado para aplicativos com um único domínio.

NOTE
Como ocorre ao aplicar qualquer configuração OSGi para o AEM as a Cloud Service, as etapas a seguir devem ser executadas em uma instância de desenvolvedor local e, em seguida, confirmadas no código do projeto para implantação.

Para definir um mapeamento de domínio para o serviço Externalizador:

  1. Navegue até o Gerenciador de configurações por meio de:

    https://<host>:<port>/system/console/configMgr

  2. Clique em Day CQ Link Externalizer para abrir a caixa de diálogo de configuração.

    A configuração OSGi do Externalizador

    note note
    NOTE
    O link direto para a configuração é https://<host>:<port>/system/console/configMgr/com.day.cq.commons.impl.ExternalizerImpl
  3. Defina um mapeamento de Domínios. Um mapeamento consiste em um nome exclusivo que pode ser usado no código para fazer referência ao domínio, a um espaço e ao domínio:

    <unique-name> [scheme://]server[:port][/contextpath]

    Em que:

    • scheme geralmente é http ou https, mas pode ser outro protocolo.

      • A Adobe recomenda o uso de https para aplicar links https.
      • Ele é usado se o código do cliente não substituir o esquema ao solicitar a externalização de um URL.
    • server é o nome do host (seja um nome de domínio ou endereço ip).

    • port (opcional) é o número da porta.

    • contextpath (opcional) só é definido se o AEM estiver instalado como um aplicativo web em um caminho de contexto diferente.

    Por exemplo: production https://my.production.instance

    Os seguintes nomes de mapeamento são predefinidos e sempre devem ser definidos, pois o AEM depende deles:

    • local - a instância local
    • author - o DNS do sistema de criação
    • publish - o DNS do site voltado para o público
    note note
    NOTE
    Uma configuração personalizada permite que você adicione uma nova categoria, como production, staging ou até mesmo sistemas externos não-AEM, como my-internal-webservice. É útil evitar a codificação rígida desses URLs em diferentes locais na base de código de um projeto.
  4. Clique em Salvar para salvar as alterações.

Usar o serviço externalizador using-the-externalizer-service

Esta seção mostra alguns exemplos de como o serviço Externalizador pode ser usado.

NOTE
Nenhum link absoluto deve ser criado no contexto de HTML. Portanto, não use este utilitário nesses casos.
  • Para externalizar um caminho com o domínio 'publicar':

    code language-java
    String myExternalizedUrl = externalizer.publishLink(resolver, "/my/page") + ".html";
    

    Considerando o mapeamento de domínio:

    • publish https://www.website.com

    • myExternalizedUrl termina com o valor:

    • https://www.website.com/contextpath/my/page.html

  • Para externalizar um caminho com o domínio 'author':

    code language-java
    String myExternalizedUrl = externalizer.authorLink(resolver, "/my/page") + ".html";
    

    Considerando o mapeamento de domínio:

    • author https://author.website.com

    • myExternalizedUrl termina com o valor:

    • https://author.website.com/contextpath/my/page.html

  • Para externalizar um caminho com o domínio 'local':

    code language-java
    String myExternalizedUrl = externalizer.externalLink(resolver, Externalizer.LOCAL, "/my/page") + ".html";
    

    Considerando o mapeamento de domínio:

    • local https://publish-3.internal

    • myExternalizedUrl termina com o valor:

    • https://publish-3.internal/contextpath/my/page.html

TIP
Você pode encontrar mais exemplos nos Javadocs.
recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab