Guia de início rápido - Postman

Guia de início rápido: Introdução ao uso da collection do Postman da Amazon Ads API

A collection do Postman da Amazon Ads API inclui scripts para facilitar o gerenciamento de credenciais de autenticação e autorização para chamar a API, bem como requisições pré-criadas para demonstrar usos comuns da API.

Como alternativa ao nosso passo a passo de introdução , muitos dos nossos usuários iniciantes podem achar o Postman útil para compreender a API.

A configuração rápida abaixo oferece instruções passo a passo para configurar a collection do Postman para fazer requisições à API.

📘

Passo a passo em vídeo

Vídeos de demonstração são incorporados para cada etapa abaixo. Você também pode ver o passo a passo completo no YouTube.

Antes de você começar

Para completar este guia, você precisará de:

• O client ID e o client secret de um aplicativo cliente do Login with Amazon aprovado para usar a Amazon Ads API. Consulte Integração se você ainda não tiver sido aprovado para acesso.
• Credenciais de login para uma conta de usuário da Amazon que gerencia contas do Amazon Ads.
• Postman, uma ferramenta de terceiros que permite aos desenvolvedores fazer chamadas de API por meio de uma interface de usuário. Você pode usar a desktop ou o aplicativo web-based.

📘

A interface do usuário do Postman

Os termos dos elementos da IU do Postman usados ​​neste documento estão alinhados com os usados ​​pelo Postman. Consulte a documentação da interface do Postman para obter mais informações e recursos visuais.

 

Configuração rápida

Importe os arquivos de collection e environment

Video

1. Baixe o arquivo de environment do Postman e arquivo de collection do GitHub.
2. Importe os dois arquivos para o Postman. Para verificar a importação:
   • Selecione o ícone Collections na barra lateral esquerda. Você deve ver a collection Amazon Ads API .
   • Selecione o ícone Environments na barra lateral esquerda. Você deve ver o Amazon Ads API Environment .
3. Em Environment, selecione Amazon Ads API Environment para ativar o environment.

Configurar o Environments

Video

1. Na barra lateral esquerda, selecione Environment e, em seguida, selecione Amazon Ads API Environment .

2. Defina manualmente o valor atual para as seguintes variáveis:

   Variável	Descrição
   client_id	O client ID do aplicativo cliente do Login with Amazon aprovado para usar a API.
   client_secret	O client secret do aplicativo cliente do Login with Amazon aprovado para usar a API.
   redirect_uri	Um URL incluído na configuração "Allowed Return URLs" do seu aplicativo do Login with Amazon. No environment, isso é definido https://amazon.comcomo padrão. Você ainda precisará habilitar esta URL em Login with Amazon ou alterar esta variável para refletir outra URL permitida.

   📘

   Nota

   O ambiente padrão é configurado para acessar o host norte-americano para a API. Para alterações adicionais para acessar a API em outras regiões, consulte Regiões .

3. Salve as alterações em seu environment.

Gerar um código de authorization grant

Video

1. Na barra lateral esquerda do Postman, vá para Collections > Amazon Ads API .

2. Selecione a pasta Auth na collection e localize a request GET de Auth grant login .

3. Abra o Console no footer do Postman.

4. Clique em Send para fazer a requisição. Essa ação testa a URL na janela de visualização do Postman e registra a URL apropriada no console do Postman.

5. Copie o authorization grant url do console, visite o local em um navegador da Web e faça login com uma conta de usuário da Amazon que gerencie contas do Amazon Ads.

   🚧

   Importante

   Certifique-se de estar desconectado de qualquer outra conta de usuário da Amazon antes de visitar o URL de autorização.

6. Você é redirecionado para o redirect_urique você definiu em seu arquivo de environment. Um código de concessão de autorização é anexado a esta URL como o parâmetro code de consulta.

O endereço na barra de URL do seu navegador deve se parecer com o seguinte, onde XXXXXestá o código de authorization grant:

https://amazon.com/?code=XXXXX&scope=advertising%3A%3Acampaign_management

Anote este código para uso na próxima etapa. O código de autorização representa a permissão da conta de usuário para seu aplicativo cliente para acessar os serviços e dados de publicidade dessa conta.

📘

Nota

Os códigos de concessão de autorização expiram em 5 minutos. Um novo código pode ser gerado repetindo o processo de authorization grant.

Recupere tokens de acesso e atualização

Video

1. Na pasta Auth da collection, selecione a request POSTAccess token from auth grant .
2. No Body desta requisição, localize o parâmetro code e digite o código recuperado na etapa anterior.
3. Em Send envie a requisição.

Uma requisição bem-sucedida define as variáveis access_token​​e refresh_tokenem seu ambiente.

📘

expiração do token

Os tokens de acesso expiram em 60 minutos. Os tokens de atualização não expiram.

Para solicitações subsequentes à API, um script na collection do Postman da Amazon Ads API usa o token de atualização para gerar novos tokens de acesso automaticamente, conforme necessário.

Recuperar um profile ID

Video

1. Selecione a pasta Profiles na collection.
2. Selecione a request GETProfiles e em Send para enviar a requisição.

A resposta a essa requisição é uma lista de profiles , cada um dos quais representa a conta do Amazon Ads da conta do usuário em um marketplace específico.

Por padrão, um script na collection define a variável profileId no environment para o primeiro profile retornado na resposta. Esse valor é usado em chamadas subseqüentes. Para saber mais sobre profiles, consulte Profiles.

Próximos passos

Seu environment do Postman agora tem as credenciais necessárias para fazer outras requisições à Amazon Ads API:

• Seu client ID
• Um token de acesso(access token)
• Um profile ID

A collection do Postman é configurada para incluir esses valores nos headers das requisições subsequentes.

Para testar uma primeira chamada típica para a API, consulte Fazendo sua primeira chamada .

📘

Suporte técnico

Se você tiver dificuldade para se conectar à API Amazon Ads, visite nossa página de suporte técnico para obter informações.

Se você acredita que o problema está relacionado a esta documentação ou à própria collection do Postman, abra um problema em nosso repositório GitHub.

Alterações opcionais

Regiões

O environment fornecido é configurado para chamar o host norte-americano para a Amazon Ads API. Para acessar dados e serviços de publicidade na Europa ou na Ásia, altere as variáveis api_url​​, auth_grant_urle token_urlno ambiente para os hosts regionais apropriados.

Região	api_url	auth_grant_url	token_url
NA	https://advertising-api.amazon.com	https://www.amazon.com/ap/oa	https://api.amazon.com/auth/o2/token
EU	https://advertising-api-eu.amazon.com	https://eu.account.amazon.com/ap/oa	https://api.amazon.co.uk/auth/o2/token
FE	https://advertising-api-fe.amazon.com	https://apac.account.amazon.com/ap/oa	https://api.amazon.co.jp/auth/o2/token

Para obter uma lista de marketplaces em cada região, consulte API endpoints .