Publicado originalmente em 20 de fevereiro de 2019
Observe que o Postman é uma ferramenta de desenvolvimento de terceiros. A D2L recomenda que você avalie a adequação do Postman à sua organização antes de usá-lo.
D2L e padrões de integração
Na D2L, temos e continuaremos a ser fortes apoiadores dos padrões de integração. No final de 2016, adicionamos suporte ao OAuth 2.0 para o desenvolvimento de aplicativos de API do Brightspace. O OAuth 2.0 é uma estrutura de autenticação padrão aberta que fornece vários fluxos de autenticação, incluindo o fluxo OAuth de três etapas. Ele permite que os desenvolvedores escrevam aplicativos que acessam diferentes serviços em nome de um usuário.
Observe que continuaremos a oferecer suporte ao nosso modelo de autenticação de par de id/chave, mas nosso foco será o suporte contínuo e o crescimento do OAuth 2.0. Um exemplo disso é uma atualização recente que fizemos em nossa implementação do OAuth 2.0. Em nossa versão de março de 2019, adicionamos suporte para usando o parâmetro Client_ID request para se identificar ao enviar solicitações para o endpoint do token. Esperamos que esta atualização seja benéfica para muitos desenvolvedores do Brightspace.
Por que realizamos essa atualização?
A inclusão do valor Client_ID não afetará nenhum aplicativo OAuth 2.0 existente. Além de sermos mais aderentes ao padrão, por meio da Comunidade de Desenvolvedores, ouvimos de nossos clientes que nossa implementação do OAuth 2.0 não era compatível com algumas ferramentas de API de terceiros. Mais especificamente, os desenvolvedores do Brightspace não conseguiram usar o Postman com a API do Brightspace, pois ela incluiu o valor Client_ID na solicitação para executar uma interação baseada no OAuth 2.0.
O que é Postman?
O Postman é a ferramenta de teste de API líder de mercado. Está disponível para download em www.getpostman.com.
O Postman é poderoso e fácil de usar e seu Centro de Suporte é muito útil. Entre seus muitos recursos, acreditamos que o seguinte será muito útil para os desenvolvedores da API do Brightspace:
- Crie ambientes de desenvolvimento (por exemplo, um para o local de teste do Brightspace e outro para o local de produção)
- Criar variáveis de ambiente (por exemplo, Domínio do Brightspace, Versão da API)
- Crie coleções que forneçam a capacidade de executar várias chamadas de API em sequência
- Usar JavaScript para passar variáveis para uma chamada de API
- Usar JavaScript para armazenar variáveis após uma chamada de API
Comece com um aplicativo Brightspace OAuth 2.0
O uso do Postman com o Brightspace requer um aplicativo Brightspace OAuth 2.0. Se você ainda não tiver um aplicativo OAuth 2.0, poderá criar um em sua instância do Brightspace navegando até Como começar a usar o OAuth 2.0ou usar o aplicativo público fornecido no Ambiente de desenvolvimento do Brightspace (certifique-se de ingressar no grupo de desenvolvedores para acessar o arquivo "Credenciais da instância do desenvolvedor", que contém os detalhes do aplicativo público OAuth 2.0).
Criar uma coleção do carteiro e conectá-la ao Brightspace
Antes de começar, certifique-se de ter Postman instalado. Use as etapas a seguir para configurar a autenticação do Postman com seu aplicativo Brightspace:
- Inicie o Postman.
- Você deve ser solicitado com um Começando janela. Sob o padrão Criar novoselecionar Coleção.
- Especifique um Nome para sua nova coleção (por exemplo, "Teste de API do Brightspace").
- Selecione o ícone Autorização guia.
- Do Tipo menu suspenso, selecione OAuth 2.0.
- Pelo Adicionar dados de autenticação a menu suspenso, selecione Cabeçalhos de solicitação.
- Clique Obter novo token de acesso.
- O Obter novo token de acesso janela aberta. Você precisará configurar cada campo da seguinte maneira:
- Forneça um Nome do token (por exemplo, "Token do ambiente de desenvolvimento do Brightspace").
- Tipo de concessão definido como Código de autorização.
- Defina o URL de retorno de chamada como:
https://oauth.pstmn.io/v1/browser-callback
(conforme Documentação do Postman OAuth 2.0) - Defina o URL de autenticação como: https://auth.brightspace.com/oauth2/auth
- Defina o URL do token de acesso como: https://auth.brightspace.com/core/connect/token
- ID do cliente deve corresponder ao valor da ID do cliente do seu aplicativo Brightspace.
- Segredo do cliente deve corresponder ao valor do Segredo do cliente do seu aplicativo Brightspace.
- Âmbito deve corresponder ao valor do Escopo do seu aplicativo Brightspace.
- Estado pode ser qualquer valor. Esse valor é um recurso de segurança destinado a proteger contra falsificação de solicitação entre sites. Para fins de teste, esse valor não é muito importante; Mas, para aplicativos de produção, certifique-se de usar um valor criptograficamente seguro.
- Cliente Autorização definido como Enviar como cabeçalho de autenticação básica.
- Clique Token de solicitação. Você será solicitado com uma janela de login para sua instância do Brightspace. Insira o Nome de usuário e Senha do usuário com o qual você deseja executar solicitações de API e clique em Iniciar sessão. Se for bem-sucedido, você verá uma solicitação de consentimento para confirmar o uso do aplicativo. Aceite esse prompt (observe que esse prompt ocorre apenas para um usuário na primeira vez que ele acessa o aplicativo).
- A janela deve fechar e você verá um Token de acesso valor inserido na coleção. Role até a parte inferior da janela e clique em Usar token.
- Clique Criar para criar sua coleção.
Agora você tem uma coleção do Postman conectada ao Brightspace usando o OAuth 2.0. O próximo passo é adicionar uma solicitação de API à sua coleção.
Adicionar solicitações do Brightspace à sua coleção do Postman
Um dos aspectos poderosos do Postman é que você pode adicionar uma ou várias solicitações de API a uma coleção.
Para adicionar uma solicitação à sua coleção
- Clique Novo.
- Selecione um Pedir e insira um Nome da solicitação e Solicitar descrição.
- Certifique-se de que sua coleção seja Selecionado como o local de salvamento. Clique Salvar em {sua coleção}.
Neste ponto, você será levado de volta à página inicial do Postman, mas agora você tem a opção de adicionar uma solicitação de API específica. Você pode fornecer ao Postman os detalhes de qualquer rota da API do Brightspace que deseja testar neste estágio. Você pode adicionar uma Solicitação para OBTER uma lista de todos os questionários existentes em um curso específico.
- Para o primeiro campo, especifique OBTER como o método HTTP.
- No campo URL da solicitação, você precisa criar o endpoint completo da API. Isso inclui o URL da instância.
- Comece com o URL da instância.
- Insira a URL da API que você deseja chamar (por exemplo, /d2l/api/le/(version)/(orgUnitId)/quizzes/ ).
- Substitua o valor (versão) pela versão atual da API.
- Substitua seu orgUnitId pelo curso a ser direcionado.
- Clique no ícone Autorização e garantir Herdar autenticação do pai durante Tipo está definido.
- Com os detalhes da solicitação inseridos e a autorização específica, clique em Enviar para testar a nova solicitação.
- Agora você deve receber uma resposta 200 com uma série de questionários atualmente disponíveis para o usuário ver na orgUnit específica.
Se não houver questionários, você pode esperar um erro 404 para nenhum questionário encontrado. Se o usuário não tiver permissões para ver os questionários, você receberá um erro 403 não autorizado.
Usos avançados do carteiro
O Postman contém recursos adicionais que economizam tempo e aumentam a compreensão de uma rota de API. Carteiro permite Coleta e/ou Ambiente Variáveis. Isso permite que você substitua valores em suas solicitações para adicionar rapidamente novos pontos de extremidade ou testar em diferentes instâncias. Aqui estão algumas ideias para ajudá-lo a começar:
- Criar uma variável de ambiente que defina o URL da sua instância do Brightspace
- Crie uma variável de versão para armazenar o valor fornecido em seus URLs de API
Outro ótimo recurso é Scripts. O Postman contém um ambiente de tempo de execução (baseado em Node.js) que permite adicionar código dinâmico às suas solicitações antes da solicitação ou logo após a realização de uma chamada. Os usuários podem adicionar scripts de pré-solicitação e pós-solicitação a pastas de coleções ou solicitações específicas. Os scripts são ótimos para situações como:
- Sondagem da versão da API de uma instância e fornecimento do valor em uma variável para uma solicitação subsequente
- Salvando o valor de um OrgUnitId e passando-o para uma pesquisa em uma solicitação a seguir
- Executar uma função de cálculo antes de enviar os dados em uma API POST
Problemas com o Postman e o Brightspace
Nossa avaliação do Postman foi promissora e positiva. No entanto, tivemos alguns problemas dos quais você deve estar ciente.
Limpeza de cookies: No momento da publicação deste artigo, notamos que não há problemas na primeira vez que os tokens OAuth são gerados. No entanto, as tentativas subsequentes têm problemas. Para resolver esse problema, recomendamos que Limpar cookies dentro do Postman.
Sem redirecionamento de login: ao gerar um token OAuth, o usuário é enviado do Postman para a página de login da instância do Brightspace na qual está desenvolvendo. Não há opções para redirecionar para uma página de login diferente do Brightspace no navegador integrado do Postman. Isso só será um problema se a conta de usuário com a qual você está desenvolvendo não estiver registrada no provedor de identidade da sua página de login principal.
Estamos avaliando as duas questões acima. No entanto, acreditamos que ambos são problemas dentro do Postman. Estaríamos abertos a sugestões sobre como contornar melhor esses problemas e forneceremos todas as atualizações que recebermos neste artigo.
Conclusão
Conte-nos sobre sua experiência usando o Postman e compartilhe conosco quaisquer coleções do Postman que você desenvolver. Se houver outro cliente de teste de API que você prefira ao Postman, gostaríamos de saber para que também possamos testá-lo.
Para obter mais treinamento sobre como usar o Postman, consulte Aprenda carteiro com Paul.
Figura: Visualize os detalhes de uma solicitação na tela de solicitação.
