Lista de verificação da REST API V2
- Tópicos:
- Authentication
Este documento agrega em um local os requisitos obrigatórios e as práticas recomendadas para programadores que implementam aplicativos clientes que consomem a API REST V2 da Autenticação do Adobe Pass.
O documento a seguir deve ser considerado parte de seus critérios de aceitação ao implementar a REST API V2 e deve ser usado como uma lista de verificação para garantir que todas as etapas necessárias tenham sido tomadas para obter uma integração bem-sucedida.
Requisitos obrigatórios
1. Fase de registro
Requisitos | Riscos | |
---|---|---|
Escopo do aplicativo registrado | Use um aplicativo registrado com escopo REST API v2. | Riscos de acionamento de respostas de erro "Não autorizado" HTTP 401, sobrecarga de recursos do sistema e latência crescente. |
Armazenamento em cache de credenciais do cliente | Armazene as credenciais do cliente no armazenamento persistente e reutilize-as para cada solicitação de token de acesso. | Há risco de perda de autenticação quando as credenciais do cliente forem geradas novamente. |
Cache de tokens de acesso | Armazene os tokens de acesso no armazenamento persistente e reutilize-os até que expirem. Não solicite um novo token para cada chamada REST API v2. Atualize os tokens de acesso somente quando eles expirarem. | Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações". |
2. Fase de configuração
Requisitos | Riscos | |
---|---|---|
Recuperação de configuração |
Recupere a resposta de configuração somente quando for necessário solicitar que o usuário selecione o MVPD (provedor de TV) antes da Fase de autenticação.
| Riscos de sobrecarga dos recursos do sistema e aumento da latência. |
Armazenamento em Cache de Seleção do Provedor de TV |
Armazene a seleção do provedor de TV por assinatura (MVPD) do usuário no armazenamento persistente para usá-la em todas as fases subsequentes:
| Riscos de sobrecarga dos recursos do sistema e aumento da latência. |
3. Fase de autenticação
Requisitos | Riscos | |
---|---|---|
Início do mecanismo de pesquisa |
Inicie o mecanismo de sondagem sob as seguintes condições:
Autenticação executada em um aplicativo secundário (tela)
| Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações". |
Interrupção do mecanismo de pesquisa |
Pare o mecanismo de sondagem sob as seguintes condições:
Sessão de autenticação e expiração do código
Novo código de autenticação gerado
| Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações". |
Configuração do mecanismo de pesquisa |
Configure a frequência do mecanismo de sondagem nas seguintes condições:
Autenticação executada em um aplicativo secundário (tela)
| Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações". |
Armazenamento em cache de perfis |
Armazene partes das informações de perfil do usuário no armazenamento persistente para melhorar o desempenho e minimizar chamadas desnecessárias da API REST v2.
atributos
| Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações". |
4. (Opcional) Fase de pré-autorização
Riscos ao ignorar nossos sistemas de monitoramento e alerta.
Somente um número limitado de códigos de erro aprimorados garante uma nova tentativa, enquanto a maioria requer resoluções alternativas, conforme especificado no campo de ação.
Verifique se qualquer mecanismo de repetição implementado para recuperar decisões de pré-autorização não resulta em um loop infinito e se ele limita as tentativas a um número razoável (ou seja, 2-3).
5. Fase de autorização
Permitir que os fluxos continuem sem interrupções mesmo que o token de mídia expire durante a reprodução e solicite uma nova decisão de autorização contendo um token de mídia (novo) quando o usuário fizer sua próxima solicitação de reprodução, independentemente de ser para o mesmo recurso ou para um diferente.
Os fluxos ao vivo executados por longos períodos podem optar por solicitar uma nova decisão de autorização após operações de vídeo, como pausar conteúdo, iniciar interrupções comerciais ou modificar configurações no nível do ativo quando o MRSS for alterado.
Riscos ao ignorar nossos sistemas de monitoramento e alerta.
Somente um número limitado de códigos de erro aprimorados garante uma nova tentativa, enquanto a maioria requer resoluções alternativas, conforme especificado no campo de ação.
Certifique-se de que qualquer mecanismo de repetição implementado para recuperar decisões de autorização não resulte em um loop infinito e que limite as tentativas a um número razoável (ou seja, 2-3).
6. Fase de saída
Implemente a API de logout para permitir que os usuários desconectem manualmente, encerrando seus perfis autenticados e seguindo o nome de ação da API REST v2 especificado para cada perfil removido:
- Para MVPDs que oferecem suporte a um endpoint de logout, o aplicativo cliente requer a navegação até o "url" fornecido em um user-agent.
- Para perfis do tipo "appleSSO", o aplicativo cliente exige que o oriente o usuário para também fazer logoff do nível do parceiro (configurações do sistema da Apple).
7. Parâmetros e cabeçalhos
Mesmo quando a solicitação é originada de um servidor em nome de um dispositivo, o valor do cabeçalho AP-Device-Identifier deve refletir o identificador real do dispositivo de streaming.
Mesmo quando a solicitação se origina de um servidor em nome de um dispositivo, o valor do cabeçalho X-Device-Info deve refletir as informações reais do dispositivo de streaming.
Além disso, alguns campos, como o dispositivo de streaming connectionIp e connectionPort, são obrigatórios para recursos como Autenticação da Base Inicial do Spectrum.
Para plataformas sem um identificador de hardware, gere um identificador exclusivo a partir dos atributos do aplicativo e mantenha-o.
8. Tratamento de erros
Somente um número limitado de códigos de erro aprimorados garante uma nova tentativa, enquanto a maioria requer resoluções alternativas, conforme especificado no campo de ação.
A maioria dos códigos de erro aprimorados listados na documentação Códigos de Erro Aprimorados - REST API V2 pode ser totalmente evitada se manipulada corretamente durante a fase de desenvolvimento, antes de iniciar o aplicativo.
Há risco de mau funcionamento do aplicativo cliente devido à falta de tratamento dos códigos de erro aprimorados, causando mensagens de erro não claras, orientação incorreta do usuário ou comportamento de fallback incorreto.
Somente um número limitado de códigos de erro HTTP garante uma nova tentativa, enquanto a maioria requer resoluções alternativas.
A maioria das respostas de erro HTTP pode ser totalmente evitada se manipulada corretamente durante a fase de desenvolvimento antes da inicialização do aplicativo.
Há risco de mau funcionamento do aplicativo cliente devido à falta de tratamento dos códigos de erro aprimorados, causando mensagens de erro não claras, orientação incorreta do usuário ou comportamento de fallback incorreto.
9. Ensaios
Desenvolva e teste o aplicativo usando os ambientes oficiais de não produção de Autenticação do Adobe Pass:
- Pré-produção
- Estágios de lançamento
Execute controle de qualidade (QA) completo nesses ambientes antes de iniciar a produção da versão.
Os aplicativos cliente não devem prosseguir para a Produção de Versão sem antes concluir a validação completa em ambientes que não sejam de produção.
A falta de um caminho de depuração curto e eficiente pode impedir que o Suporte e a Engenharia da Adobe intervenham rapidamente.
Práticas recomendadas
1. Fase de registro
Verifique se qualquer mecanismo de repetição para manipular erros "Não autorizados" do HTTP 401 atualiza primeiro o token de acesso antes de repetir a solicitação original.
2. Fase de configuração
3. Fase de autenticação
Valide o código de autenticação enviado por meio da entrada do usuário no aplicativo secundário (segunda) (tela) antes de chamar a API /api/v2/authenticate nas seguintes condições:
Autenticação executada no aplicativo secundário (tela) com mvpd pré-selecionado
- Use Retomar sessão de autenticação - POST /api/v2/{serviceProvider}/sessions/{code}
Autenticação executada no aplicativo secundário (tela) sem mvpd pré-selecionado
- Use Recuperar sessão de autenticação - GET /api/v2/{serviceProvider}/sessions/{code}
O aplicativo cliente receberia um erro se o código de autenticação fornecido fosse digitado incorretamente ou caso a sessão de autenticação expirasse.
Suporte a fluxos não básicos, caso o negócio de aplicativos clientes exija:
- Fluxos de acesso degradados (recurso premium)
- Fluxos de acesso temporário (recurso premium)
- Fluxos de acesso de logon único (recurso padrão)
4. (Opcional) Fase de pré-autorização
5. Fase de autorização
6. Fase de saída
7. Parâmetros e cabeçalhos
Reutilize o código da API REST v1 para chamar a API DCR e recuperar um token de acesso.
8. Ensaios
Verifique se os seguintes fluxos básicos foram testados em dispositivos e plataformas:
Fluxos de autenticação
- Cenário de autenticação do aplicativo primário (tela)
- Cenário de autenticação de aplicativo secundário (tela)
(Opcional) Fluxos de pré-autorização
- Cenário de decisões de licenciamento de teste
- Testar cenário de decisões de negação
Fluxos de autorização
- Cenário de decisões de licenciamento de teste
- Testar cenário de decisões de negação
Fluxos de logout
Além disso, teste outros fluxos de acesso, se aplicável:
- Fluxos de acesso degradados (recurso premium)
- Fluxos de acesso temporário (recurso premium)
- Fluxos de acesso de logon único (recurso padrão)
Aborde as principais integrações do MVPD (abrangendo os provedores mais usados).
Resumo
Tokens de acesso em cache
partes do cache de perfis
Recurso de Degradação de Suporte (se necessário ao negócio)
Recurso TempPass Suporte (se necessário ao negócio)
Recurso de Logon Único Suporte (se necessário ao negócio)
Repetir ajuste do mecanismo
Repetir ajuste do mecanismo
Validação de token de mídia
Implementar tratamento de erros HTTP