Manual do desenvolvedor de aplicativos

Autenticação da API

Ao gravar um aplicativo que faz chamadas de API para o Learning Manager, você precisa registrar o aplicativo usando o aplicativo do administrador de integração.

As APIs do Learning Manager usam a estrutura OAuth 2.0 para autenticar e autorizar os seus aplicativos cliente.

Procedimento

1. Configurar seu aplicativo

Você pode configurar o aplicativo com a ID do cliente e o segredo do cliente para usar os pontos de extremidade apropriados. Depois de registrar o aplicativo, você pode obter a clientId e o clientSecret. Obter URL deve ser usado no navegador, pois ele autentica os usuários do Learning Manager usando as suas contas pré-configuradas, como SSO, Adobe ID e assim por diante.

Após a autenticação bem-sucedida, o navegador redireciona para o redirect_uri mencionado no URL acima. Um código de parâmetro é anexado junto com o uri de redirecionamento.

2. Obtenha o token de atualização do código

POST https://learningmanager.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded

Corpo da solicitação post:

3. Obter um token de acesso do token de atualização

URL para obter o token de acesso:

POST https://learningmanager.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded

Corpo da solicitação post:

URL para verificar os detalhes do token de acesso

GET https://learningmanager.adobe.com/oauth/token/check?access_token=<access_token>

Limitação de uso

Um token de acesso é válido por sete dias. Depois de um dia, você tem que gerar um novo token de acesso usando o token de atualização. Se você gerar um novo token de acesso a partir do token de atualização enquanto um token de acesso existente ainda for válido, o token existente será retornado.

Alguns dos termos usados com frequência na API do Learning Manager são explicados abaixo para a sua referência.

Inclui

Os desenvolvedores podem acessar um único modelo de objeto de API e também vários modelos associados a esse modelo. Para acessar os modelos relacionados subsequentes, você precisa entender a relação de cada modelo com outros modelos. O parâmetro Includes permite que os desenvolvedores acessem os modelos dependentes. É possível usar um separador de vírgulas para acessar vários modelos. Para obter exemplos de uso e mais detalhes sobre inclusões, consulte a seção modelo de API de exemplo nesta página.

Solicitação de API

As solicitações de API podem ser feitas através de uma solicitação HTTP. Dependendo do ponto de extremidade e do desenvolvedor de métodos, você pode ter a opção de vários verbos HTTP, como GET, PUT, POST, DELETE, PATCH etc. Para algumas solicitações, os parâmetros de consulta podem ser transmitidos. Ao fazer uma solicitação para um modelo de dados específico, o usuário também pode solicitar modelos relacionados conforme descrito nas especificações da API JSON. A estrutura de uma Solicitação de API típica é descrita no exemplo de uso do modelo.

Resposta da API

Quando uma solicitação de API é feita por um cliente, um documento SON é obtido de acordo com a especificação da API JSON. A resposta também contém o código Status HTTP, que o desenvolvedor pode verificar para executar as próximas etapas apropriadas na lógica do aplicativo. A estrutura de uma Resposta de API típica é descrita em exemplo de uso de modelo.

Erros

Quando uma solicitação de API falha, uma resposta de erro é obtida. O código de status HTTP retornado na resposta indica a natureza do erro. Os códigos de erro são representados com números para cada modelo na referência da API. 200, 204, 400 e 404 são alguns dos erros comuns representados em APIs que indicam problemas de acesso HTTP.

Campos

Os atributos do objeto de API e suas relações são coletivamente chamados de Campos. Consulte a API JSON para obter mais informações. Você pode usar Campos como um parâmetro enquanto faz chamadas de API para buscar um ou mais atributos específicos do modelo. Na ausência do parâmetro Campos, a chamada da API busca todos os atributos disponíveis do modelo. Por exemplo, na seguinte chamada de API, fields[skill]=name busca o atributo name apenas do modelo de habilidade.

https://learningmanager.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name

Paginação

Às vezes, uma solicitação de API resulta em uma longa lista de objetos a serem retornados na resposta. Nesses casos, o atributo de paginação permite que o desenvolvedor busque os resultados sequencialmente em termos de várias páginas, onde cada página contém um intervalo de registros. Por exemplo, o atributo de paginação no Learning Manager permite definir o número máximo de registros a serem exibidos em uma página. Além disso, você pode definir o valor do intervalo dos registros a serem exibidos na página.

Classificação

A classificação é permitida em modelos de API. Com base no modelo, escolha o tipo de classificação a ser aplicado para os resultados. A classificação pode ser aplicada em ordem crescente ou decrescente. Por exemplo, se você especificar code sort=name, ele será classificado por nome em ordem crescente. Se você especificar code sort=-name, ele será classificado por nome em ordem decrescente. Consulte Especificação da API JSON para obter mais informações.

Ilustração de uso da API

Vamos considerar um cenário em que um desenvolvedor deseja obter o nome da habilidade, os pontos máximos atribuídos ao nível de habilidade e os pontos obtidos pelo aluno para essa habilidade.

Um modelo userSkill nas APIs do Learning Manager consiste em id, type, dateAchieve, dateCreated, pointsEarned como atributos padrão. Portanto, quando um desenvolvedor usa o método GET para adquirir detalhes do modelo userSkill, os dados atuais pertencentes aos atributos padrão são mostrados na saída de resposta.

Mas, nesse cenário, o desenvolvedor quer obter o nome da habilidade e os pontos de nível de habilidade para o usuário. A API do Learning Manager permite que você acesse essas informações relacionadas usando os campos de relacionamento e inclua o parâmetro. Os modelos associados para userSkill são obtidos na tag de relacionamentos. Você pode obter os detalhes de cada modelo associado chamando esses modelos junto com o userSkill. Para obter essas informações, use o parâmetro code include com valores separados por ponto (ponto) para cada um dos modelos associados. Você pode usar vírgula como separador para solicitar outro modelo, como user include=skillLevel.skill,course

Chamada de API

https://learningmanagerqe1.adobe.com/primeapi/v1/users/%7buserId%7d/userSkills/%7bid%7d?include=skillLevel.skill&fields%5bskill%5d=name&fields%5bskillLevel%5d=maxCredits&fields%5buserSkill%5d=pointsEarned

Por exemplo, userId pode ser 746783 e userSkills id: 746783_4426_1.

Resposta da chamada de API