Externalizar URLs

No caso do AEM, a Externalizador é um serviço OSGi que permite transformar programaticamente um caminho de recurso (por exemplo, /path/to/my/page) em um URL externo e absoluto (por exemplo, https://www.mycompany.com/path/to/my/page) ao prefixar 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 como, à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

Pronto para uso, o serviço Externalizador mapeia alguns identificadores de domínio para prefixos absolutos de URL 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]"
   ]
}

Para substituir o preview e publish valores, use as variáveis de ambiente do Cloud Manager conforme descrito no artigo Configuração do OSGi para o AEM as a Cloud Service e a definição de valores predefinidos AEM_CDN_DOMAIN_PUBLISH e AEM_CDN_DOMAIN_PREVIEW variáveis.

Configurar o serviço externalizador

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.

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.

   

   OBSERVAÇÃO

   O link direto para a configuração é https://<host>:<port>/system/console/configMgr/com.day.cq.commons.impl.ExternalizerImpl

3. Definir um Domínios mapeamento. 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 (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
   OBSERVAÇÃO

   Uma configuração personalizada permite adicionar uma nova categoria, como production, staging ou 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

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

• Para externalizar um caminho com o domínio "publicar":

  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":

  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":

  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