Coisas para concluir antes de começar
Antes de começar com este tutorial, você precisa ter concluído as 3 etapas abaixo:
- Solicitar credenciais da API de membro do sandbox
- Criar uma caixa de areia ORCID conta
- Configure seu google oauth playground
Para este tutorial, usaremos ORCIDambiente de teste do ORCID Sandbox. O Sandbox funciona exatamente como a produção ORCID Registro, com algumas exceções:
- Sandbox só envia e-mails para mailinator.com endereços
- A maioria das ferramentas do assistente de importação não funciona no Sandbox
- Links de menu para conteúdo informativo (Sobre, Para Pesquisadores, Associação etc.) não funcionam no Sandbox
- Sandbox não contém dados de produção
Solicitar credenciais da API de membro do sandbox
As credenciais da API consistem em um ID do Cliente e de um cliente secreto que são necessários para coletar IDs autenticados e/ou permissões de usuário para interagir com seus ORCID registro. Solicite suas credenciais do Sandbox aqui. Adicione uma observação para informar que você está testando com o Google OAuth Playground. Esteja ciente de que este é um processo manual e pode levar até 24 horas para que as credenciais sejam criadas.
Criar uma caixa de areia ORCID conta
Em uma nova janela ou guia, visite https://sandbox.orcid.org/register
- Digite seu nome e endereço de e-mail e clique no botão “próximo”. IMPORTANTE! Não use um endereço de e-mail real! Em vez disso, crie um endereço que termine em @mailinator.com
- Preencha a etapa 2 do formulário de registro com uma senha e vá para a etapa 3.
- Selecione sua configuração de visibilidade preferida, aceite os termos de uso, clique na caixa ao lado do texto “Não sou um robô” e, por fim, clique no botão “registrar”.
Lembre-se do e-mail e da senha – você precisará deles ao longo do tutorial!
Configure seu Playground do Google OAuth
- Acesse Playground do Google OAuth
- Clique no ícone de engrenagem no canto superior direito para abrir o Configuração do OAuth 2.0
- Altere a lista suspensa de endpoints Oauth para Custom e insira as seguintes configurações e clique em Close
Importante! Mantenha o Google OAuth Playground aberto para não perder as configurações feitas nas etapas acima. Você também pode salvar a URL que permite inicializar o Playground com essas configurações (para obter a URL, clique no ícone do link ao lado do ícone de engrenagem no canto superior direito).
Coleta autenticada ORCID IDs e permissões
ORCID as integrações usam “OAuth de 3 pernas” para autenticar usuários e solicitar permissão para interagir com seus registros. Qualquer integração pode solicitar permissões de leitura usando a API pública. ORCID os membros podem usar a API Member para solicitar permissões de leitura e gravação.
Nesta seção, veremos as etapas que sua própria integração personalizada precisaria concluir para obter um iD e permissão para ler e escrever em um ORCID registro
Obtendo um Autenticado iD e registrar a permissão de acesso de um usuário envolve seguir OAuth 2.0, um protocolo padrão da indústria para autorização. OAuth permite que um usuário dê a um site ou aplicativo acesso a informações de conta armazenadas em outro site, sem fornecer a senha a esse site.
Se você já fez login em um site usando o Google ou o Facebook em vez de suas credenciais para esse site específico, você já usou o OAuth!
O processo OAuth inclui 3 etapas:
- Criar um URL de autorização
- Obter um código de autorização
- Troque o código de autorização por um token de acesso
Para iniciar o processo OAuth, precisaremos criar um URL de autorização especial que envie os usuários para um ORCID tela de login. Este URL consiste em Ponto de extremidade de autorização, mais parâmetros que identificam sua organização e as permissões que você deseja solicitar.
Para solicitar permissão para adicionar/atualizar atividades (afiliações, financiamento, trabalhos, revisão por pares, recursos de pesquisa) e para adicionar/atualizar itens pessoais (outros nomes, palavras-chave, países, URLs de pesquisadores, sites e identificadores externos pessoais), o URL de autorização será:
https://sandbox.orcid.org/oauth/authorize?client_id=[APP-****************]&response_type=code&scope=/read-limited%20/activities/update%20/person/update&redirect_uri=https://developers.google.com/oauthplaygroundMas podemos usar o playground do Google OAuth para nos ajudar a criar o URL de autorização
Adicione /activities/update, /person/update, /read-limited no campo scopes e clique em autorizar APIs.
A URL de autorização teria sido criada usando as informações que você inseriu nos campos de configuração e escopo.
An ORCID aparecerá a tela de login; entre na sua conta Sandbox com o endereço de e-mail e a senha que você usou para criar seu ORCID conta no início deste tutorial. Depois de fazer login, a tela OAuth será exibida. O nome do cliente e os escopos relevantes que foram incluídos na URL de autorização serão exibidos nesta tela. Para conceder acesso você precisa clicar em 'Autorizar acesso'
Após conceder a permissão, você será redirecionado de volta ao Google OAuth Playground, pois esse era o URI de redirecionamento associado à sua credencial do Sandbox. Um código de autorização de 6 caracteres aparecerá no final do URI de redirecionamento na barra de endereço do navegador (e sob o Passo 2 seção à esquerda da página no google oauth playground)
Depois de ter um Código de Autorização, você pode trocá-lo por um token de acesso e o Authenticated iD do usuário que fez login, que você precisará para realizar as ações de API para as quais solicitou permissão.
Se você perder o token de acesso, poderá concluir o processo novamente, mas primeiro precisará revogar a permissão do aplicativo cliente se estiver usando o mesmo ORCID Eu iria. A permissão pode ser revogada removendo o aplicativo cliente da seção "Organizações confiáveis" na página "Partes confiáveis"
Em uma situação do mundo real, essa troca seria feita pelo seu sistema, usando uma linguagem de programação como PHP, Java ou Ruby on Rails. Para este tutorial, usaremos o Google OAuth Playground para simular um aplicativo da web.
Clique 'Trocar código de autorização para tokens'
Depois de clicar em “Código de autorização de troca para tokens” Seu token de acesso e autenticado iD aparecerá no Pedido / Resposta seção à direita. Por favor, veja o exemplo abaixo:
Salve este token!
É importante salvar o token que você recebeu na etapa acima, pois você pode criar facilmente as chamadas que precisar fazer com ele. Recomendamos que você armazene a resposta completa da troca de token
Você agora coletou um documento autenticado ID e permissão do usuário para ler seus ORCID gravar e atualizar seus ORCID registro.
Escrevendo para um ORCID registro (POST)
Nesta seção, adicionaremos uma afiliação educacional ao seu registro Sandbox. No exemplo a seguir, estamos usando o endpoint /education com o XML correto para adicionar as informações, mas você também pode adicionar Emprego ou Trabalhos, por exemplo. Veja nosso Documentação do Github para obter mais exemplos de arquivos e endpoints e as permissões necessárias para cada um.
Aqui está um exemplo de XML de educação que você pode usar para este exercício:
<?xml version="1.0" encoding="UTF-8"?>
<education:education
xmlns:common="http://www.orcid.org/ns/common" xmlns:education="http://www.orcid.org/ns/education"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.orcid.org/ns/education ../education-3.0.xsd ">
<common:department-name>department-name</common:department-name>
<common:role-title>role-title</common:role-title>
<common:start-date>
<common:year>1948</common:year>
<common:month>02</common:month>
<common:day>02</common:day>
</common:start-date>
<common:end-date>
<common:year>1948</common:year>
<common:month>02</common:month>
<common:day>02</common:day>
</common:end-date>
<common:organization>
<common:name>common:name</common:name>
<common:address>
<common:city>common:city</common:city>
<common:region>common:region</common:region>
<common:country>AF</common:country>
</common:address>
<common:disambiguated-organization>
<common:disambiguated-organization-identifier>http://dx.doi.org/10.13039/100000001</common:disambiguated-organization-identifier>
<common:disambiguation-source>FUNDREF</common:disambiguation-source>
</common:disambiguated-organization>
</common:organization>
<common:url>http://tempuri.org</common:url>
<common:external-ids>
<common:external-id>
<common:external-id-type>grant_number</common:external-id-type>
<common:external-id-value>external-identifier-value</common:external-id-value>
<common:external-id-url>http://tempuri.org</common:external-id-url>
<common:external-id-relationship>self</common:external-id-relationship>
</common:external-id>
<common:external-id>
<common:external-id-type>grant_number</common:external-id-type>
<common:external-id-value>external-identifier-value2</common:external-id-value>
<common:external-id-url>http://tempuri.org/2</common:external-id-url>
<common:external-id-relationship>self</common:external-id-relationship>
</common:external-id>
</common:external-ids>
</education:education>Retorne à guia do navegador para o Google Playground. Se você não manteve a guia aberta, você pode reinicializar a sessão com a URL que você salvou anteriormente (Clicando em OK no aviso que aparece). Ou você pode configurar a chamada novamente preenchendo todos os campos relevantes, certificando-se de que eles se pareçam com as capturas de tela abaixo:
- Verifique se o • Configuração tem o seu cliente ID e segredo do cliente
- abaixo da Etapa 2 no google oauth playground, você deve ter seu token de acesso preenchido
Ele ainda deve ter o token de antes ou você pode preenchê-lo do exercício anterior assim: - Abaixo da Etapa 3 Clique Adicionar cabeçalhos, insira os valores abaixo e clique em Adicionar e Fechar
- Nome do cabeçalho: ACEITAR
- Valor do cabeçalho: aplicativo/vnd.orcid+xml
- Abaixo da Etapa 3: Configurar solicitação para API, defina Método HTTP como POST.
- Na série Solicitar URI campo digite:
https://api.sandbox.orcid.org/v3.0/[ORCID ID]/education
Substituir [ORCID ID] com o iD para seu registro Sandbox, formate XXXX-XXXX-XXXX-XXXX com o qual você obteve permissão para interagir. - Clique Tipo de conteúdo > Personalizadas e digite application/vnd.orcid+xml Clique Adicionar, então clique Fechar.
- Clique Digite o corpo da solicitação.
Copie o XML de afiliação educacional na parte superior desta seção e cole-o no Corpo da solicitação caixa de texto
OPCIONAL: Na série Corpo da solicitação caixa de texto, edite o XML para refletir sua instituição.
Por , use o Registro ROR para encontrar o ROR ID para sua instituiçãon.
Clique Fechar.
- Clique Envie o pedido.
Os resultados aparecerão no Pedido / Resposta seção à direita. Role até o final - se você vir HTTP/1.1 201 Criado, sua afiliação educacional foi adicionada com sucesso!
Salve também seu código put que será necessário na próxima seção!
Visite a visualização pública do seu registro Sandbox em https://sandbox.orcid.org/[ORCID ID] para ver sua nova afiliação educacional.
Observe que Source mostra o nome do cliente da API que adicionou a afiliação – este é um elemento chave que ajuda outros sistemas a consumir ORCID os dados determinam se essa informação tem autoridade.
Atualizando um ORCID registro (PUT)
Em uma situação do mundo real, pode ser necessário atualizar a afiliação de um pesquisador. Nesta seção, atualizaremos nossa afiliação educacional para incluir uma data de término.
Os códigos de venda são códigos numéricos curtos que fazem referência a um item específico no ORCID registro. Você usa o código put com as chamadas de API para atualizar, excluir ou ler um item específico (em oposição a um resumo de itens).
Cada item no ORCID iD recebe um código put que o identifica exclusivamente. Ao ler um registro ou seção inteira, o código put pode ser encontrado como um atributo do item. Quando chamar um item específico em um registro, o código put é usado para identificar o item. Os códigos de colocação são únicos dentro do tipo de item a que se referem. Usando este exemplo, apenas um trabalho no ORCID O registro terá o código put 733535, embora 733535 também possa ser usado como um código put para um item de financiamento ou uma palavra-chave.
Quando você publica um item no registro de um pesquisador, a resposta da API conterá o código put desse item. Você pode armazenar o código de venda para usá-lo mais tarde se precisar ler, atualizar ou excluir esse item.
Para descobrir o código de venda de um determinado item que não temos, basta ler o registro ou um resumo da seção onde esse item está localizado. O código put para o item que queremos modificar será retornado na resposta.
No exemplo abaixo, estamos atualizando um único item educacional.
Observação: se você salvou o código put para sua afiliação educacional, pode pular para a etapa 4 abaixo. Se você não salvou o código put, comece com a etapa 1 abaixo.
- Primeiro precisamos obter um colocar código para a afiliação educacional que você acabou de adicionar, abra uma nova janela do Google Playground e configure-a seguindo as quatro primeiras etapas da seção de primeiros passos
- Desta vez, no campo Request URI, insira https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/educations . Observe que adicionamos /educations ao final do URI e que está no plural. Isso significa que estamos buscando um resumo de todos os itens educacionais neste registro, não apenas um (colocamos no singular e adicionamos o /put-code do item no final)
- Clique em 'Enviar a solicitação' e você deverá ver algo como a imagem abaixo no Pedido / Resposta seção. Encontre o colocar código para a afiliação educacional que você adicionou na seção anterior (será um número diferente do destacado aqui).
- Mudar Método HTTP para PUT
- Clique Adicionar cabeçalhos e certifique-se de que Accept e Content-type estejam definidos como application/vnd.orcid+xml
- Na série Solicitar URI campo digite:
https://api.sandbox.orcid.org/v3.0/[ORCID ID]/education/[PUT CODE]
Substituir [ORCID ID] com o iD para seu registro Sandbox, formato XXXX-XXXX-XXXX-XXXX e [PUT CODE] com o put-code para sua afiliação educacional - Pegue o XML da seção POST novamente e clique Digite o corpo da solicitação e cole-o.
- Edite a data de término da sua afiliação educacional
- Clique Fechar.
- Clique em Enviar a solicitação.
- Os resultados aparecerão no Pedido / Resposta seção à direita. Role até o final - se você vir HTTP / 1.1 200 OK, sua afiliação educacional foi atualizada com sucesso! Se você vir uma mensagem de erro, verifique se os valores do cabeçalho em Adicionar cabeçalhos não foram alterados para texto ilegível, ex: application%2Fvnd.orcid%2Bxml”
- Visite o visão pública do seu registro Sandbox em https://sandbox.orcid.org/[ORCID ID] para ver sua afiliação educacional atualizada com a nova data de término preenchida.
Lendo um ORCID Gravar (GET)
Retorne à guia do navegador para o Google Playground. Se você não manteve a guia aberta, você pode reinicializar a sessão com a URL que você salvou anteriormente (Clicando em OK no aviso que aparece). Ou você pode configurar a chamada novamente preenchendo todos os campos relevantes, certificando-se de que eles se pareçam com as capturas de tela abaixo:
- Verifique se o • Configuração tem o seu cliente ID e segredo do cliente
- Passo 2 você deve ter o seu token de acesso preenchido
Ele ainda deve ter o token de antes ou você pode preenchê-lo do exercício anterior assim: - Etapa 3 Clique Adicionar cabeçalhos, insira os valores abaixo e clique em Adicionar e Fechar
- Nome do cabeçalho: ACEITAR
- Valor do cabeçalho: aplicativo/vnd.orcid+xml
- As configurações da etapa 3 devem se parecer com a captura de tela abaixo:
- Defina o método HTTP para ENTRE.
- No campo URI de solicitação, digite:
https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/record
Substituir [ORCID ID] com o iD para seu registro Sandbox, formato XXXX-XXXX-XXXX-XXXX
Note o Ponto final é a palavra no final do URI. Neste caso, estamos lendo um resumo de todo o registro, então terminamos a URL com /record como mostrado acima. - Clique Envie o pedido
No campo Solicitação/Resposta você deverá ver um resumo XML de todo o registro. Será um pouco parecido com o exemplo abaixo, que mostra a primeira parte da resposta. Destacamos os códigos de venda conforme discutido na seção anterior
