Este tutorial irá guiá-lo através da adição de informações a um ORCID registro, formatando dados de acordo com o ORCID esquema de mensagem e atualização ou exclusão de dados que você adicionou anteriormente a um ORCID registro.
- Obtenha algumas credenciais de cliente
- Obtenha permissão para atualizar os registros
- Adicionando itens
- Atualizando itens
- Excluindo itens
- Mais informação
Obtenha algumas credenciais de cliente
As credenciais do cliente são o nome de usuário e a senha que seu aplicativo / site usará para acessar o ORCID API. Qualquer pessoa pode se registrar para obter credenciais de API pública somente leitura, ORCID membros podem se registrar para a API membro.
Você exigirá credenciais de API de membro para o servidor de teste sandbox, bem como um registro de teste no ORCID sandbox para testar a adição e atualização de itens no ORCID registro.
Você pode solicitar credenciais de API de membro da sandbox para construir e testar seu aplicativo. Essas credenciais permitem que você faça chamadas para a API de membro premium do sandbox para ler, gravar e atualizar ORCID registros. O acesso ao ambiente de teste sandbox está disponível gratuitamente para qualquer pessoa, mesmo se você não for um ORCID organização membro.
Note: Se você estiver usando um ORCID sistema de provedor de serviços certificado que já suporta ORCID, você não precisa se registrar para obter credenciais da API sandbox, a menos que queira experimentar o ORCID funcionalidade de integração dentro do ambiente Sandbox.
O sandbox permite que você crie contas de usuário de teste e desenvolva sua integração sem ter que se preocupar em afetar os dados ao vivo (produção) ORCID Registro. A sandbox se comporta da mesma maneira que a produção ORCID Registro com algumas exceções.
Criação de uma conta de teste
A fim de testar o ORCID API e chamadas de API, como leitura e adição de informações a um ORCID registro, você também precisará criar um teste ORCID gravar na caixa de areia. Isso pode ser feito por meio da interface do usuário, bem como na produção ORCID Registro. Vamos para https://sandbox.orcid.org/register e registre-se para uma conta.
Endereços de e-mail do Mailinator
O servidor sandbox só envia e-mails para Mailinator (@mailinator.com) endereços de e-mail para não enviar spam aos servidores de e-mail involuntariamente. Você não receberá um e-mail de verificação ou notificação de redefinição de senha, a menos que use um endereço @mailinator.com, e a verificação é necessária para fazer edições manuais nos registros do sandbox. Saiba mais sobre suas caixas de entrada públicas gratuitas Aqui. Se você não deseja usar um Mailinator endereço, anote seu nome de usuário e senha (pois você os usará para conceder autorização ao seu aplicativo durante o teste) e entre em contato conosco para solicitar assistência com a verificação.
Mailinator é um serviço de e-mail que possui um serviço público gratuito e um serviço privado pago. Para testar, você pode usar o serviço público totalmente gratuito. Saiba mais sobre seus níveis aqui.
Mailinator é um serviço de terceiros que não é gerenciado ou mantido por ORCID. Recomendamos que você analise como esse serviço funciona e suas limitações antes de usar esses endereços.
Obtenha permissão para atualizar os registros
Para adicionar ou atualizar informações sobre um ORCID registro, você deve primeiro obter a permissão dos proprietários do registro. Apenas ORCID os membros podem pedir permissões de atualização, e isso é feito solicitando o “/ atividades / atualização”E / ou“/ pessoa / atualização”Escopos usando OAuth.
Existem dois âmbitos de atualização diferentes - um para detalhes biográficos e outro para atividades.
Objetivo | Descrição | Endpoints API |
/ pessoa / atualização | Dados biográficos - a coluna da esquerda do ORCID interface de usuário de registro. | /Morada / external-identifiers /palavras-chave /outros nomes / researcher-urls |
/ atividades / atualização | Dados da atividade de pesquisa - a coluna direita da ORCID interface de usuário de registro. | /distinção / distinções /Educação / educations /emprego / empregos /financiamento / fundings / posição-convidado / convidados-posições /Filiação / membros / peer-review / peer-reviews /qualificação / qualifications / research-resource / research-resources /serviço /Serviços /trabalhos /trabalho |
ORCID as integrações usam “3 pernas OAuth” 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 atualização. Funciona assim:
- Você cria um link especial
- Quando clicado, o usuário é enviado para ORCID
- ORCID pede ao usuário para fazer login
- ORCID pede ao usuário para conceder permissão ao seu aplicativo
- ORCID envia o usuário de volta ao seu sistema com um código de autorização
- Seu sistema troca esse código por um token de acesso
A URL de autorização personalizada inclui as informações do seu cliente, bem como os 'escopos' que especificam as áreas específicas de seu registro que você deseja acessar. Após o login, o usuário autoriza a conexão com seu sistema e é retornado à sua página de destino juntamente com um código de autorização. Este código é então usado para obter seus ORCID iD junto com um token de acesso válido para os escopos solicitados.
Você cria seu link de autorização especificando o ID do cliente de suas credenciais de API e a página de destino associada (URI de redirecionamento). Você escolhe quais permissões solicitar definindo o parâmetro de escopo.
O exemplo a seguir solicita permissão para ler dados de acesso limitado no ORCID servidor de teste sandbox. No mundo real, você exibe esse link em seu site ou o inclui em um e-mail ao solicitar que o usuário autentique e autorize. No entanto, para fins de teste, você pode simplesmente colá-lo em seu navegador da web. Substitua os dados entre colchetes pelas informações do seu cliente e certifique-se de remover os colchetes!
https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited&redirect_uri=[Your landing page]
Aquele em que o usuário clicou no link e fez login em ORCID e recebem permissões, eles são redirecionados de volta ao seu site, como este:
https://[Your landing page]?code=Q70Y3A
Você deve trocar imediatamente o código de autorização para o ORCID iD e token de acesso. O código de autorização expira após o uso. O pedido é assim e não pode ser feito em um navegador da web, deve ser feito pelo seu servidor.
URL=https://sandbox.orcid.org/oauth/token
HEADER: Accept: application/json
HEADER: Content-Type: application/x-www-form-urlencoded
METHOD: POST
DATA:
client_id=[Your client ID]
client_secret=[Your client secret]
grant_type=authorization_code
code=Six-digit code
redirect_uri=[Your landing page]
ORCID irá então devolver o autenticado do pesquisador ORCID iD e um token de acesso no formato JSON:
{"access_token":"f5af9f51-07e6-4332-8f1a-c0c11c1e3728","token_type":"bearer",
"refresh_token":"f725f747-3a65-49f6-a231-3e8944ce464d","expires_in":631138518,
"scope":"/read-limited","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}
Os tokens de acesso têm longa duração por padrão e expiram 20 anos após a emissão. O token pode ser usado várias vezes antes de expirar.
Use o token de acesso
Tokens de acesso de três etapas estão vinculados a ORCID registro. Para usá-los, você os inclui nas solicitações de API que você faz para ler ou atualizar esse registro.
Ao solicitar permissão para interagir com um ORCID registro do usuário, você especifica um ou mais 'escopos'. Cada escopo permite que você faça certas coisas, como ler o registro ou atualizar uma seção específica.
3 pernas refere-se aos três atores envolvidos na obtenção de permissão de um usuário; ORCID, seu sistema e o próprio usuário.
/autenticar
Este escopo é usado para coletar o ORCID iD e ler informações públicas apenas no registro. Todos os outros escopos de três pernas incluem a permissão de autenticação, portanto, esse escopo pode ser omitido se for solicitado qualquer outro acesso. Este escopo está disponível na API de membros ou pública.
/ read-limited (Member API apenas)
Este escopo é usado para obter acesso para ler itens públicos e de visibilidade limitada em um ORCID registro. Este escopo está disponível apenas na API de membros.
/ atividades / atualização (apenas API de membro)
Este escopo é usado para escrever, atualizar e excluir itens nas seções de afiliação, financiamento, trabalhos, atividades profissionais, recursos de pesquisa e revisão por pares de um ORCID registro. Este escopo está disponível apenas na API de membros.
/ pessoa / atualização (apenas API de membro)
Este escopo é usado para escrever, atualizar e excluir itens nas seções de outros nomes, palavras-chave, países, urls de pesquisador, sites e identificadores pessoais externos do registro. Este escopo está disponível apenas na API de membros.
código aberto
Este escopo é usado por integradores OpenID quando um id_token é necessário. Quando o escopo openid é incluído, o Registro retorna um id_token dentro da resposta do token e concede ao cliente permissão para acessar o endpoint de informações do usuário para aquele usuário. Este escopo está disponível na API pública e membro.
Observe que o escopo 'openid' não começa com '/' como o outro ORCID Escopos de API. Isso ocorre porque o escopo 'openid' não é definido por ORCID, mas em vez disso definido pela especificação OpenID Connect. Por favor, veja nosso Documentação OpenID para entender melhor.
Múltiplos escopos
Vários escopos podem ser solicitados em uma única interação, listando os escopos no URL de autenticação com um espaço codificado entre cada um, como escopo = / leitura limitada% 20 / atividades / atualização% 20 / pessoa / atualização
Acesso completo
Se você deseja acesso total para ler e editar um registro, inclua três escopos em seu URL de autenticação: / read-limited, / Activities / update e / person / update. No URL, eles apareceriam como escopo = / leitura limitada% 20 / atividades / atualização% 20 / pessoa / atualização
Escopos de duas pernas (credencial do cliente)
Para algumas atividades, você não precisa pedir permissão ao usuário. Escopos OAuth de duas pernas são solicitados diretamente do ORCID API e não exigem que o pesquisador conceda permissão. Tokens com esses escopos são válidos por 20 anos e podem ser reutilizados
/ read-public
Este escopo é usado para ler informações públicas em um único ORCID identificação, procure por ORCID registros ou para ler informações resumidas (somente API para membros). Este escopo está disponível na API Membro ou Pública.
/ webhook
Este escopo permite que um aplicativo cliente registre um webhook em um ORCID registro, a fim de receber notificações quando um registro é atualizado. Este escopo está disponível para premium ORCID apenas membros.
Adicionando itens
Itens (obras, emprego, financiamento, revisão por pares, etc.) podem ser adicionados a um ORCID gravar usando o ORCID API membro. Eles aparecerão com o nome do seu cliente como a “fonte” do item.
Itens (obras, emprego, financiamento, revisão por pares, etc.) podem ser adicionados a um ORCID gravar usando o ORCID API membro. Para fazer isso, você deve primeiro obter permissão do pesquisador usando OAuth e formatar os metadados do item usando o ORCID esquema de mensagem.
Depois de formatar os dados e coletar os ORCID iD e token de acesso, você faz uma solicitação de API usando HTTP POST, especificando o endpoint relevante.
Method: POST
Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]data: link to file or text of single employment item to add
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment
A chamada abaixo adiciona um novo emprego afiliação a um registro no servidor de teste sandbox:
<?xml version="1.0" encoding="UTF-8"?>
<employment:employment [...]>
[...]
</employment:employment>
A API retornará uma mensagem 201 para indicar que o item foi postado corretamente, junto com o item colocar código. Seu cliente será listado como o fonte do item.
Confira nossa solução de problemas página se uma mensagem diferente for retornada. Você precisará salvar o armazene o código de colocação e o token de acesso para fazer atualizações ou remover o item.
An ORCID O registro pode conter informações sobre o trabalho de um pesquisador, afiliações, financiamento, revisão por pares e muito mais.
Itens em ORCID registros podem ser divididos em asserções que conectam o ORCID Detentor de ID com uma atividade ou afiliação. Essas afirmações podem ser adicionadas a um ORCID registro pelo pesquisador que possui o registro, ou por sistemas que o pesquisador concedeu permissão para fazê-lo. Chamamos a entidade que adicionou uma afirmação a um ORCID registre o fonte.
Exemplos
Seguindo nossos princípios de transparência e abertura, acreditamos ser importante poder ver a fonte da afirmação - quem está adicionando essa informação ao registro. Aqui está como fazemos isso:
- Quando um pesquisador (ou seu delegado indivíduo de confiança) adiciona uma afirmação ao seu registro, ORCID registra automaticamente essa pessoa como a fonte
- Quando um sistema aprovado pelo pesquisador adiciona uma afirmação a um registro, ORCID registra automaticamente o proprietário do sistema (um ORCID membro) como a fonte.
Exibimos o nome da fonte na interface do usuário e o disponibilizamos (com seu identificador exclusivo) na API:
No entanto, os fluxos de trabalho de informações de pesquisa podem ser mais complicados do que isso, e a fonte real de uma afirmação pode ser obscurecida involuntariamente por um sistema adicionando um item em nome de uma pessoa ou outro sistema. Para garantir a transparência, precisamos distinguir entre quem fez a conexão entre a pessoa e o item e quem adicionou o item ao registro. Como acima, quem adiciona o item ao ORCID registro é o fonte; quem quer que crie a conexão entre o ORCID iD e o item é o origem da afirmação.
Por exemplo:
- Um pesquisador importa dados para seu ORCID registro de um sistema, como um assistente de pesquisa e link. O pesquisador está fazendo a afirmação conectando seus iD com o item, então eles são o origem da afirmação; enquanto o sistema é a entidade que adiciona a asserção ao ORCID registro - o fonte
- Um pesquisador interage com o Sistema A (o origem da afirmação), que usa serviços fornecidos pelo Sistema B para atualizar ORCID registros, tornando o Sistema B o fonte
Incentivamos nossa comunidade a tomar medidas para preservar e compartilhar informações sobre a origem da afirmação, para que todos possam se beneficiar ao ver a fonte.
Para mais informações, consulte:
Atualizando itens
É uma boa prática manter as informações que você adicionou ao ORCID registros em dia. Por exemplo, adicionar datas de término do emprego quando os funcionários saem ou adicionar os identificadores de artigos publicados aos conjuntos de dados.
ORCID os membros podem atualizar as informações que adicionaram anteriormente a um ORCID registro. Apenas um item pode ser atualizado por vez e só pode ser atualizado usando as credenciais do cliente que o criou inicialmente.
Para facilitar a atualização, certifique-se de armazene o código de colocação e o token de acesso ao criar itens.
Formate o item atualizado in ORCID esquema de mensagem com as informações alteradas e incluir o armazenado colocar código.
<?xml version="1.0" encoding="UTF-8"?> <employment:employment put-code="739288" [...]> [...] </employment:employment>
Chame a API:
Method: PUT Content-type: application/vnd.orcid+xml or application/vnd.orcid+jsonnAuthorization type and Access token: Bearer [stored access token]Data: link to file or text of affiliation to update URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment/739288
A API retornará uma mensagem 200 OK para indicar que o item foi atualizado corretamente. Verifique nossa página de solução de problemas se uma mensagem diferente for retornada.
Todos os itens (exceto o texto da biografia) em um ORCID registro tem um colocar código:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<record:record path="/0000-0001-2345-6789" xmlns:internal="https://www.orcid.org/ns/internal" [...]>
<funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0"> [...]
</record:record>
Este código put pode ser usado para fazer uma chamada à API para recuperar os dados completos de um item. Os seguintes itens podem ser consultados usando um colocar código:
Ponto final | Descrição |
/ endereço / [colocar código] | Um país ou região individual |
/biografia | O campo da biografia: área de texto livre que só o pesquisador pode editar |
/ educação / [colocar código] | Um item de afiliação educacional individual |
/ email / [colocar código] | Um endereço de e-mail individual associado ao registro |
/ emprego / [colocar código] | Um item de afiliação de emprego individual |
/ external-identifier / [colocar código] | Um identificador externo individual vinculado em outro sistema |
/ financiamento / [colocar código] | Uma atividade de financiamento individual |
/ palavras-chave / [colocar código] | Uma palavra-chave individual relacionada ao pesquisador e seu trabalho |
/ outros-nomes / [colocar código] | Um nome adicional individual pelo qual o pesquisador é conhecido |
/ revisão por pares / [colocar código] | Uma atividade individual de revisão por pares |
/ researcher-urls / [colocar código] | Um link externo individual para a página pessoal ou de perfil do pesquisador |
/ work / [colocar código] | Um trabalho de pesquisa individual |
/ works / [colocar código1], [colocar código2], [colocar código3] | Trabalhos de pesquisa individuais em massa (até 100) |
Usando o endpoint da seção e o código put, você pode chamar a API usando o mesmo token de acesso para obter aquele item específico por completo. Este exemplo de chamada recupera o item de financiamento total 4413 no formato XML usando a API membro no servidor sandbox.
Method: GET Accept: application/vnd.orcid+xml Authorization type and Access token: Bearer [stored access token]URI: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/funding/4413
A API retornará uma mensagem 200 OK para indicar que a mensagem foi recebida com sucesso e retornará o XML completo do item de financiamento:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<funding:funding put-code="4413" path="/0000-0002-9227-8514/funding/4413" visibility="public" [...] >
[...]
</funding:funding>
Você pode verificar o fonte de um item ao lê-lo, se você quiser saber quem o adicionou.
Excluindo itens
Você pode querer excluir itens que adicionou anteriormente, por exemplo, se eles foram adicionados por engano ou se foram substituídos por outros itens.
Se você adicionou dados que precisam ser excluídos, por exemplo, se eles foram associados ao ORCID iD, então você pode fazer uma solicitação HTTP DELETE especificando o ponto final relevante, juntamente com o ORCID eu ia, token de acesso armazenado e código de colocação armazenado. Apenas um item pode ser excluído por vez e você só pode excluir itens adicionados pelo seu cliente. Você pode excluir itens mesmo quando o usuário revogou a permissão.
Este exemplo de chamada exclui o item de emprego com o código put “739288” de um registro ”
Method: DELETE
Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment/739288
Mais informação
Identificadores persistentes
A maioria dos itens dentro de um ORCID registro tem um ou mais identificadores persistentes. Eles vêm em dois 'sabores', identificadores de trabalho e identificadores de organização.
Por favor consulte o nosso lista de identificadores suportados para a API V3.0. Ocasionalmente, adicionamos novos tipos a pedido de ORCID membros que gostariam de usá-los ao adicionar itens ao registro.
ORCID suporta o uso de Identificadores ROR, Identificadores GRID e Crossref Funder Registry identificadores para desambiguar organizações em ORCID Registros.
Para mais informações, consulte Trabalho com identificadores de organização
Embora os identificadores Ringgold ainda existam dentro do ORCID registro, a partir de 1º de agosto de 2023, ORCID não receberá mais atualizações do banco de dados de identificadores de organização RINGGOLD usado por nosso Registro, nem poderemos processar ou usar IDs RINGGOLD criados após essa data. Veja nosso Perguntas frequentes para mais informações
Agrupamento
Os itens são agrupados em ORCID registros com base em seus identificadores. Você pode descobrir que os itens adicionados são adicionados a um grupo existente.
Obras em ORCID são agrupados com base em seus identificadores e na relação desses identificadores com a obra. Existem quatro tipos de relacionamentos:
- Eu: o identificador refere-se apenas àquela obra e pode ser agrupado com outras obras que possuem o mesmo identificador
- Parte da: a obra faz parte deste identificador e não pode ser agrupada com outras obras
- Versão de: esses identificadores se aplicam a versões alternativas da obra e podem ser agrupados com a própria e com a versão dos identificadores
- Fundado por: esses identificadores se aplicam ao financiamento da obra. Esses identificadores não são usados para trabalhos de agrupamento.
Nossa API fornece suporte para isso no XSD. Cada item possui um atributo de índice de exibição que indica sua classificação dentro de seu grupo. O maior índice de exibição é o item preferido selecionado pelo pesquisador. Itens adicionados por meio da API que não foram classificados pelo pesquisador têm índice de exibição 1 e são usados como fonte preferencial padrão dentro do grupo até serem alterados pelo pesquisador. O índice de exibição também determina a ordem de serviço ao ler o ORCID gravar com a API.
Para obter mais informações sobre agrupamento em ORCID registros, por favor veja nosso artigo de apoio.
Visibilidade
Controle do pesquisador de ORCID registros é um dos ORCID'pontuação princípios. Os itens são adicionados a ORCID registros com a configuração de visibilidade padrão dos pesquisadores.
Visibilidade indica a configuração de privacidade do item, com base na preferência de visibilidade definida pelo usuário. Se uma tag de visibilidade for incluída quando as informações forem postadas por meio da API, ela será ignorada. Em vez disso, as informações serão publicadas de acordo com a preferência de visibilidade padrão do usuário, conforme definido em suas preferências de conta.
Itens públicos podem ser lidos por qualquer pessoa por meio da API e são exibidos no registro público do pesquisador. Itens de terceiros confiáveis são devolvidos apenas por meio da API para clientes com acesso limitado para leitura; eles não estão no registro público do pesquisador. Os itens privados são visíveis apenas para o pesquisador e a fonte do item – os únicos itens privados retornados por meio da API são aqueles que foram adicionados ao registro por meio de sua integração Mais sobre as configurações de visibilidade no ORCID Lista de Presentes.
Notificações de usuário
Quando um ORCID membro adiciona ou atualiza um item em um registro, ORCID informa ao usuário que isso aconteceu.
Eles recebem uma notificação em seu ORCID caixa de entrada. Sempre que houver uma mudança nos dados em um ORCID registro, o usuário recebe uma notificação com informações básicas sobre a mudança, incluindo o nome do cliente que realiza a atualização, a data da mudança e o item no ORCID registro que foi atualizado. Veja nosso Base de conhecimento do usuário para mais informações sobre notificações.
ORCID registros na sandbox também têm caixas de entrada em funcionamento. Recomendamos consultar regularmente as caixas de entrada de seus testes ORCID registros ao planejar como seus sistemas irão agendar atualizações de dados.