Tutorial de API: ler dados em um registro

Recomendamos que os desenvolvedores testem a API pública no servidor de teste sandbox antes de usar a versão de produção. Abaixo estão as etapas sobre como se registrar para credenciais de API públicas nos ambientes Sandbox e Produção.

• Faça login na sua ORCID registro:
  Servidor de produção: https://orcid.org/signin
  Servidor de teste de sandbox: https://sandbox.orcid.org/signin
• Clique no seu nome no canto superior direito
• Clique Ferramentas de desenvolvimento da opção do menu
  Nota: Para acessar as Ferramentas do desenvolvedor, você deve verificar seu endereço de e-mail. Se você ainda não verificou seu endereço de e-mail, será solicitado que o faça antes de se registrar para obter credenciais de API públicas
• Leia e concorde com os 'ORCID Termos de serviço de APIs públicas
• Clique no botão “Registre-se para ORCID Botão “Credenciais da API Pública”.

Preenchendo o formulário de detalhes do aplicativo

• Depois de se registrar para obter suas credenciais de API públicas, você será direcionado de volta às Ferramentas do desenvolvedor (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• Você precisa preencher o formulário de detalhes do aplicativo apresentado para registrar um novo aplicativo.
  • Nome: O nome do seu aplicativo. Isso será exibido para os usuários quando eles concederem permissão ao seu aplicativo para obter seus ORCID iD, e será exibido em seu Lista de organizações confiáveis. Recomendamos usar o nome de sua organização ou serviço (por exemplo, o nome de um jornal).
  • URL do aplicativo: O site que o usuário pode visitar para saber mais sobre seu aplicativo. Isso também será exibido em seus Lista de organizações confiáveis.
  • Descrição da Aplicação: Informações sobre o aplicativo que você está desenvolvendo e como usará as do usuário ORCID eu ia. Isso será exibido para os usuários na tela do OAuth.

Adicionando URIs de redirecionamento

Depois que o usuário autorizar seu aplicativo, ele será retornado a um URI que você especificar. Você deve fornecer esses URIs com antecedência ou seus usuários de integração enfrentarão um erro.

• Insira seu URI de redirecionamento na caixa fornecida
• Se você precisar inserir mais de 1 URI de redirecionamento, clique em 'Adicionar outro URI de redirecionamento'

Observe:

• Preço: URIs HTTPS são aceitos na produção
• Domínios registrados DEVO correspondem exatamente aos domínios usados, incluindo subdomínios
• Registre todos os URIs de redirecionamento totalmente, sempre que possível. Esta é a opção mais segura e a que recomendamos. Para obter mais informações sobre URIs de redirecionamento, consulte nosso Perguntas frequentes sobre URI de redirecionamento

Salvando seu aplicativo

Depois de preencher o formulário de inscrição e adicionar seus URIs de redirecionamento, você pode salvar sua inscrição.

• Clique em 'Salvar meu aplicativo e gerar meu ID de cliente e segredo'

Você será direcionado de volta para a página de ferramentas do desenvolvedor, que agora incluirá suas credenciais de cliente da API pública

Atualizando suas credenciais

Fazer uma alteração nas informações do seu aplicativo é muito simples.

• Edite as informações relevantes e clique em 'Salvar aplicativo'

Use suas credenciais

Agora que você tem suas credenciais, é hora de começar a usar o ORCID API pública!

Observe que podemos transferir suas credenciais para o membro API se você se tornar um ORCID membro no futuro.

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.

Qualquer pessoa com credenciais de API públicas ou de membro pode receber um / read-public token de acesso. Para obter um token, você faz uma chamada para o ORCID Ponto de extremidade do token da API.

Esse processo geralmente é conhecido como fluxo OAuth de credenciais do cliente ou OAuth de 2 etapas.

Um exemplo de chamada para obter um token de acesso para ler dados públicos na sandbox - substitua os espaços reservados por suas credenciais (certifique-se de remover os colchetes.

URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  METHOD: POST
  DATA: 
    client_id=[Your public API client ID]
    client_secret=[Your public API secret]
    grant_type=client_credentials
    scope=/read-public

Em seguida, você receberá um token de acesso semelhante ao seguinte. O token retornado é de longa duração (não expira por aproximadamente 20 anos) e pode ser usado várias vezes para recuperar dados públicos de ORCID Registros. 

{"access_token":"4bed1e13-7792-4129-9f07-aaf7b88ba88f","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138518,
"scope":"/read-public","orcid":null}

Nota: Todos os tokens com o escopo / authenticate agora também têm o escopo / read-public incluído. Se você usar apenas o escopo / authenticate, poderá usar os tokens de acesso armazenados para ler dados públicos sem precisar obter novamente um token de acesso. 

Integradores que usam a API membro podem usar o / read-public escopo para ler ORCID registrar resumos.

Para obter / acesso limitado de leitura, você deve pedir permissão ao pesquisador. Você faz isso usando OAuth. Especificamente, "OAuth de 3 pernas".

Para obter mais informações, consulte nosso Tutorial da API: Leia os dados em um ORCID registro

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.

Crie o link de autorização e obtenha um código de autorização

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

Troque o código de autorização por um ORCID iD e token de acesso

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.

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.

Este exemplo de chamada recupera um resumo do completo ORCID registro em formato XML usando a API membro no servidor sandbox. Você precisa de um token de acesso para fazer solicitações de API para a API Pública ou Membro.

Method: GET Accept: application/vnd.orcid+xml
Authorization type and Access token: 
Bearer [Stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/record

A API retornará uma mensagem 200 OK, indicando que a solicitação foi recebida com sucesso e o resumo completo do ORCID registro, incluindo resumos de itens individuais.

<?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>

Cada item (trabalho, financiamento, emprego, etc.) tem um colocar código. Isso pode ser usado para obter detalhes completos do item, se necessário.

A ORCID o registro é dividido em seções individuais para tornar a leitura do registro mais rápida e consistente. Você pode primeiro ligar para uma seção para receber seu resumo e, em seguida, ligar usando o código de colocação de um item individual para receber informações robustas sobre aquele item.

Uma tabela das seções de resumo que você pode usar a API para ler é apresentada a seguir.

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:

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

Exemplo de chamada: GitHub

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.

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.

A ORCID o registro oferece suporte à “negociação de conteúdo”. Isso significa que as máquinas e outros sistemas podem pedir ORCID registro de metadados pessoais em diferentes formatos.

Um desses formatos é JSON-LD, que usa o schema.org vocabulário, especificamente o tipo de pessoa, que conectamos com obras, organizações e outros identificadores. Também oferecemos suporte a XML, JSON, RDF XML e tartaruga, e implementamos compartilhamento de recursos entre origens (CORS) para facilitar o acesso aos nossos dados.

• Veja esta postagem do blog para uma visão geral de ORCID e schema.org
• veja nossa documentação técnica sobre negociação de conteúdo

Procurando um usuário usando cURL assim:

curl -iL https://orcid.org/0000-0000-0000-0000

Retornará 200 mesmo se o usuário não existir. Para evitar isso, use a negociação de conteúdo em sua chamada da seguinte maneira:

curl -iL -H 'Accept: application/xml' https://orcid.org/0000-0000-0000-0000