Políticas entre domínios de Gerenciamento de API

Este tópico fornece uma referência para as políticas de Gerenciamento de API a seguir. Para obter mais informações sobre como adicionar e configurar políticas, consulte Políticas de Gerenciamento de API.

Políticas entre domínios

  • Permitir chamadas entre domínios - Torna a API acessível por meio de clientes Adobe Flash e Microsoft Silverlight baseados em navegadores.
  • CORS - Adicionar suporte de compartilhamento de recursos entre origens (CORS) a uma operação ou a uma API para permitir chamadas entre domínios de clientes baseados em navegadores.
  • JSONP - Adiciona suporte JSON com preenchimento (JSONP) a uma operação ou a uma API para permitir chamadas entre domínios de clientes JavaScript baseados em navegadores.

Permitir chamadas entre domínios

Use a política cross-domain para tornar a API acessível por clientes baseados em navegadores do Adobe Flash e do Microsoft Silverlight.

Declaração de política

<cross-domain>
    <!-Policy configuration is in the Adobe cross-domain policy file format,
        see https://www.adobe.com/devnet-docs/acrobatetk/tools/AppSec/CrossDomain_PolicyFile_Specification.pdf-->
</cross-domain>

Exemplo

<cross-domain>
        <allow-http-request-headers-from domain='*' headers='*' />
</cross-domain>

Elementos

Nome Descrição Obrigatório
cross-domain Elemento raiz. Elementos filho devem estar de acordo com a Especificação de arquivo de política entre domínios do Adobe. Sim

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada
  • Escopos da política: todos os escopos

CORS

A política cors adiciona suporte do CORS (compartilhamento de recurso entre origens) a uma operação ou API para permitir chamadas entre domínios de clientes baseados em navegador.

Observação

Se a solicitação corresponder a uma operação com um método OPTIONS definido na API, a lógica de processamento de solicitação preliminar associada às políticas de CORS não será executada. Portanto, essas operações poderão ser usadas para implementar a lógica de processamento preliminar personalizada.

O CORS permite que um navegador e um servidor interajam e determina e solicitações entre origens específicas devem ou não ser aceitas (por exemplo, chamadas XMLHttpRequests feitas por meio de JavaScript em uma página da Web para outros domínios). Isso permite maior flexibilidade do que permitir somente solicitações com a mesma origem, mas é mais seguro do que permitir todas as solicitações entre origens.

Você precisa aplicar a política de CORS para habilitar o console interativo no portal do desenvolvedor. Consulte a documentação do portal do desenvolvedor para obter detalhes.

Declaração de política

<cors allow-credentials="false|true" terminate-unmatched-request="true|false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>http verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

Exemplo

Este exemplo demonstra como dar suporte a solicitações da versão pré-piloto, como as com cabeçalhos personalizados ou métodos diferentes de GET e POST. Para oferecer suporte a cabeçalhos personalizados e verbos HTTP adicionais, use as seções allowed-methods e allowed-headers conforme mostrado no exemplo a seguir.

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

Elementos

Nome Descrição Obrigatório Padrão
cors Elemento raiz. Sim N/D
allowed-origins Contém elementos origin que descrevem as origens permitidas para solicitações entre domínios. allowed-origins pode conter um único elemento origin que especifica * para permitir qualquer origem, ou um ou mais elementos origin que contêm uma URI. Sim N/D
origin O valor pode ser * para permitir todas as origens ou um URI que especifica uma origem única. O URI deve incluir um esquema, um host e uma porta. Sim Se a porta for omitida em um URI, a porta 80 é usada para HTTP e a porta 443 é usada para HTTPS.
allowed-methods Esse elemento é necessário se métodos diferentes de GET ou POST forem permitidos. Contém elementos method que especificam os verbos HTTP compatíveis. O valor * indica todos os métodos. Não Se esta seção não estiver presente, GET e POST são compatíveis.
method Especifica um verbo HTTP. Pelo menos um elemento method é necessário se a seção allowed-methods estiver presente. N/D
allowed-headers Esse elemento contém elementos header que especificam os nomes dos cabeçalhos que podem ser incluídos na solicitação. Não N/D
expose-headers Esse elemento contém elementos header que especificam os nomes dos cabeçalhos que ficarão acessíveis para o cliente. Não N/D
header Especifica um nome de cabeçalho. Pelo menos um elemento header é necessário em allowed-headers ou expose-headers se a seção estiver presente. N/D

Atributos

Nome Descrição Obrigatório Padrão
allow-credentials O cabeçalho Access-Control-Allow-Credentials na resposta preliminar será definido com o valor desse atributo e afetará a capacidade do cliente para enviar credenciais nas solicitações entre domínios. Não false
terminate-unmatched-request Esse atributo controla o processamento de solicitações entre origens que não correspondem às configurações de política de CORS. Quando a solicitação OPTIONS for processada como uma solicitação preliminar e não corresponder às configurações de política de CORS: se o atributo for definido como true, encerre imediatamente a solicitação com uma resposta 200 OK vazia; se o atributo for definido como false, verifique a entrada de outras políticas de CORS no escopo que são filhos diretos do elemento de entrada e aplique-as. Se nenhuma política de CORS for encontrada, encerre a solicitação com uma resposta 200 OK vazia. Quando a solicitação GET ou HEAD incluir o cabeçalho Origin (e, portanto, for processada como uma solicitação entre origens) e não corresponder às configurações de política de CORS: se o atributo for definido como true, encerre imediatamente a solicitação com uma resposta 200 OK vazia; se o atributo for definido como false, permita que a solicitação prossiga normalmente e não adicione cabeçalhos CORS à resposta. Não true
preflight-result-max-age O cabeçalho Access-Control-Max-Age na resposta preliminar será definido com o valor desse atributo e afetará a capacidade do agente do usuário para colocar em cache a resposta preliminar. Não 0

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada
  • Escopos da política: todos os escopos

JSONP

A política jsonp adiciona suporte a JSONP com padding (JSONP) a uma operação ou API para permitir chamadas entre domínios de clientes JavaScript baseados em navegador. O JSONP é um método usado em programas JavaScript para solicitar dados de um servidor em um domínio diferente. O JSONP ignora a limitação aplicada pela maioria dos navegadores da Web quando o acesso às páginas da Web precisa ser do mesmo domínio.

Declaração de política

<jsonp callback-parameter-name="callback function name" />

Exemplo

<jsonp callback-parameter-name="cb" />

Se você chamar o método sem o parâmetro de retorno de chamada ?cb=XXX, será retornado o JSON simples (sem um wrapper de chamada de função).

Se você adicionar o parâmetro de retorno de chamada ?cb=XXX, será retornado um resultado JSONP, dispondo os resultados JSON originais em torno da função de retorno de chamada como XYZ('<json result goes here>');

Elementos

Nome Descrição Obrigatório
jsonp Elemento raiz. Sim

Atributos

Nome Descrição Obrigatório Padrão
callback-parameter-name A chamada da função JavaScript entre domínios, prefixada com o nome do domínio onde a função reside totalmente qualificado. Sim N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: saída
  • Escopos da política: todos os escopos

Próximas etapas

Para obter mais informações sobre como trabalhar com políticas, consulte: