Tutorial de API: agregar y actualizar datos en un ORCID grabar

solicite solicitar credenciales de API de miembro de sandbox para construir y probar su aplicación. Estas credenciales le permiten realizar llamadas a la API de miembro premium de Sandbox para leer, escribir y actualizar. ORCID registros. El acceso al entorno de prueba de la caja de arena está disponible de forma gratuita para cualquier persona, incluso si no es un ORCID organización miembro.

Note: Si está utilizando un ORCID sistema de proveedor de servicios certificado que ya admite ORCID, no necesita registrarse para obtener las credenciales de la API de sandbox a menos que desee probar la ORCID funcionalidad de integración dentro del entorno Sandbox. 

La caja de arena le permite crear cuentas de usuario de prueba y desarrollar su integración sin tener que preocuparse por afectar los datos en vivo (producción) ORCID Registro. El sandbox se comporta de la misma manera que la producción. ORCID Registro con algunas excepciones.

Creando una cuenta de prueba

Para probar el ORCID API y llamadas API, como leer y agregar información a un ORCID registro, también necesitará crear una prueba ORCID grabar en la caja de arena. Esto se puede hacer a través de la interfaz de usuario, al igual que en la producción. ORCID Registro. Ir https://sandbox.orcid.org/register y registrarse para una cuenta.

Direcciones de correo electrónico del remitente

El servidor sandbox solo envía correos electrónicos a Mailinator (@mailinator.com) direcciones de correo electrónico para no enviar spam a los servidores de correo sin querer. No recibirá un correo electrónico de verificación o una notificación de restablecimiento de contraseña a menos que use una dirección @mailinator.com, y se requiere verificación para realizar modificaciones manuales en los registros de la zona de pruebas. Obtenga más información sobre sus bandejas de entrada públicas de uso gratuito Si no desea utilizar un Mailinator dirección, luego tome nota de su nombre de usuario y contraseña (ya que los usará para otorgar autorización a su aplicación durante la prueba) y contáctenos para solicitar ayuda con la verificación.

Mailinator es un servicio de correo electrónico que tiene un servicio público gratuito y un servicio privado de pago. Para la prueba puede utilizar el servicio público completamente gratuito. Más información sobre sus niveles aquí.

Mailinator es un servicio de terceros que no es administrado ni mantenido por ORCID. Le recomendamos que revise cómo funciona este servicio y sus limitaciones antes de utilizar estas direcciones.

Hay dos ámbitos de actualización diferentes: uno para los detalles biográficos y el otro para las actividades.

ORCID las integraciones utilizan “OAuth de 3 patas” para autenticar a los usuarios y solicitar permiso para interactuar con sus registros. Cualquier integración puede solicitar permisos de lectura utilizando la API pública. ORCID los miembros pueden usar la API para miembros para solicitar permisos de actualización. Funciona así:

• Creas un enlace especial
• Cuando se hace clic, se envía al usuario a ORCID
  • ORCID pide al usuario que inicie sesión
  • ORCID pide al usuario que otorgue permiso a su aplicación
  • ORCID envía al usuario de regreso a su sistema con un código de autorización
• Su sistema intercambia ese código por un token de acceso

La URL de autorización personalizada incluye la información de su cliente, así como los 'alcances' que especifican las áreas específicas de su registro a las que desea acceder. Después de iniciar sesión, el usuario autoriza la conexión con su sistema y regresa a su página de inicio junto con un código de autorización. Este código se utiliza luego para obtener su ORCID iD junto con un token de acceso válido para los ámbitos solicitados.

Cree el enlace de autorización y obtenga un código de autorización

Usted construye su enlace de autorización especificando el cliente de sus credenciales de API ID y la página de destino asociada (redireccionamiento URI). Usted elige qué permisos solicitar configurando el parámetro de alcance.

El siguiente ejemplo solicita permiso para leer datos de acceso limitado en el ORCID Servidor de prueba sandbox. En el mundo real, muestra este enlace en su sitio web o lo incluye en un correo electrónico cuando solicita al usuario que se autentique y autorice. Sin embargo, para fines de prueba, simplemente puede pegarlo en su navegador web. Reemplace los datos entre corchetes con la información de su cliente y asegúrese de eliminar los corchetes.

https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited&redirect_uri=[Your landing page]

Cuando el usuario haya hecho clic en el enlace, haya iniciado sesión en ORCID y se les conceden permisos, se les redirige a su sitio, así:

https://[Your landing page]?code=Q70Y3A

Cambie el código de autorización por un ORCID iD y token de acceso

Debe intercambiar inmediatamente el código de autorización por el ORCID iD y token de acceso. El código de autorización caduca con el uso. La solicitud se ve así y no se puede hacer en un navegador web, debe ser realizado por su 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 luego devolverá el autenticado del investigador ORCID iD y un token de acceso en 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"}

Los tokens de acceso tienen una larga vida de forma predeterminada y caducan 20 años después de su emisión. El token se puede usar varias veces antes de que caduque.

Usa el token de acceso

Los tokens de acceso de 3 patas están vinculados a ORCID registro. Para usarlos, debe incluirlos en las solicitudes de API que realice para leer o actualizar ese registro.

Al solicitar permiso para interactuar con un ORCID registro del usuario, usted especifica uno o más 'ámbitos'. Cada alcance le permite hacer ciertas cosas, como leer el registro o actualizar una sección en particular.

Ámbitos de 3 patas (código de autorización)

3 patas se refiere a los tres actores involucrados en la obtención del permiso de un usuario; ORCID, su sistema y el propio usuario.

/autenticar

Este alcance se utiliza para recopilar el ORCID iD y leer información pública en el registro solamente. Todos los demás ámbitos de 3 patas incluyen el permiso de autenticación, por lo que este ámbito se puede omitir si se solicita cualquier otro acceso. Este alcance está disponible en la API pública o miembro.

/ read-limited (solo miembro API)

Este alcance se utiliza para obtener acceso para leer elementos públicos y de visibilidad limitada en un ORCID registro. Este alcance solo está disponible en la API de miembros.

/ actividades / actualización (solo API para miembros)

Este alcance se utiliza para escribir, actualizar y eliminar elementos en las secciones de afiliación, financiación, trabajos, actividades profesionales, recursos de investigación y revisión por pares de un ORCID registro. Este alcance solo está disponible en la API de miembros.

/ person / update (solo API para miembros)

Este alcance se utiliza para escribir, actualizar y eliminar elementos en las secciones de otros nombres, palabras clave, países, URL de investigadores, sitios web e identificadores externos personales del registro. Este alcance solo está disponible en la API de miembros.

abierto

Este alcance lo utilizan los integradores de OpenID cuando se requiere un id_token. Cuando se incluye el alcance de openid, el Registro devolverá un id_token dentro de la respuesta del token y otorgará permiso al cliente para acceder al punto final de información del usuario para ese usuario. Este alcance está disponible en la API pública y para miembros.

Tenga en cuenta que el alcance 'openid' no comienza con un '/' como el otro ORCID Ámbitos de API. Esto se debe a que el alcance 'openid' no está definido por ORCID, pero en su lugar está definido por la especificación OpenID Connect. Por favor vea nuestro Documentación de OpenID para obtener más información.

Múltiples alcances

Se pueden solicitar múltiples alcances en una sola interacción enumerando los alcances en la URL de autenticación con un espacio codificado entre cada uno, como alcance = / lectura limitada% 20 / actividades / actualización% 20 / persona / actualización

Acceso completo

Si desea acceso completo para leer y editar un registro, incluya tres ámbitos en su URL de autenticación: / lectura limitada, / actividades / actualización y / persona / actualización. En la URL aparecerían como scope = / read-limited% 20 / activities / update% 20 / person / update

Ámbitos de 2 patas (credencial de cliente)

Para algunas actividades, no es necesario pedir permiso al usuario. Los ámbitos de OAuth de dos patas se solicitan directamente desde el ORCID API y no requieren que el investigador otorgue permiso. Los tokens con estos alcances son válidos durante 20 años y se pueden reutilizar

/ read-public

Este alcance se utiliza para leer información pública en un solo ORCID identificación, buscar ORCID registros o para leer información resumida (solo API para miembros). Este alcance está disponible en la API pública o para miembros.

/ webhook

Este alcance permite que una aplicación cliente registre un webhook en un ORCID registro, para recibir notificaciones cuando se actualiza un registro. Este alcance está disponible para premium ORCID solo miembros.

Los elementos (trabajos, empleo, financiación, revisión por pares, etc.) se pueden agregar a un ORCID grabar usando el ORCID API miembro. Para hacer esto, primero debes obtener permiso del investigador usando OAuth y formatear los metadatos del elemento usando el ORCID esquema de mensaje.

Una vez que haya formateado los datos y recopilado el ORCID iD y token de acceso, realiza una solicitud de API mediante HTTP POST, especificando el punto final 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

La llamada a continuación agrega un nuevo empleo afiliación a un registro en el servidor de pruebas sandbox:

<?xml version="1.0" encoding="UTF-8"?>      
<employment:employment [...]>     
[...]            
</employment:employment>

Ejemplo de llamada: Github

La API devolverá un mensaje 201 para indicar que el elemento se publicó correctamente, junto con el elemento poner código. Su cliente aparecerá como el fuente del artículo.

Consulta nuestras la solución de problemas página si se devuelve un mensaje diferente. Necesitará guardar el  almacenar el código de acceso y el token de acceso para realizar actualizaciones o eliminar el elemento.

An ORCID El registro puede contener información sobre el trabajo de un investigador, afiliaciones, financiamiento, revisión por pares y más.

Elementos en ORCID los registros se pueden dividir en afirmaciones que conectan el ORCID Titular de identificación con actividad o afiliación. Estas afirmaciones se pueden agregar a una ORCID registro por parte del investigador que posee el registro, o por sistemas a los que el investigador ha otorgado permiso para hacerlo. Llamamos a la entidad que agregó una aserción a una ORCID grabar el fuente.

Ejemplos

Siguiendo nuestros principios de transparencia y apertura, creemos que es importante poder ver la fuente de la afirmación: quién agrega esa información al registro. Así es como lo hacemos:

1. Cuando un investigador (o su delegado individuo de confianza) agrega una afirmación a su registro, ORCID registra automáticamente a esa persona como fuente
2. Cuando un sistema aprobado por el investigador agrega una afirmación a un registro, ORCID registra automáticamente el propietario del sistema (un ORCID miembro) como fuente.

Mostramos el nombre de la fuente en la interfaz de usuario y lo ponemos a disposición (con su identificador único) en la API:

Sin embargo, los flujos de trabajo de información de investigación pueden ser más complicados que esto, y la fuente real de una afirmación puede quedar oculta involuntariamente por un sistema que agrega un elemento en nombre de una persona u otro sistema. Para garantizar la transparencia, debemos distinguir entre quién hizo la conexión entre la persona y el elemento y quién agregó el elemento al registro. Como se indicó anteriormente, quien agregue el artículo al ORCID registro es el fuente; quien crea la conexión entre el ORCID iD y el artículo es el origen de la aserción.

Por ejemplo, mediante los siguientes elementos:

1. Un investigador importa datos a su ORCID registro de un sistema, como un asistente de búsqueda y enlace. El investigador está haciendo la afirmación que conecta sus iD con el artículo, por lo que son los origen de la aserción; mientras que el sistema es la entidad que agrega la aserción a la ORCID registro - el fuente
2. Un investigador interactúa con el Sistema A (el origen de la afirmación), que utiliza los servicios proporcionados por el Sistema B para actualizar ORCID registros, haciendo del Sistema B el fuente

Alentamos a nuestra comunidad a tomar medidas para preservar y compartir información sobre el origen de las afirmaciones, de modo que todos puedan beneficiarse al ver la fuente.

Para obtener más información, consulte:

• Vías de garantía de afirmación: ¿qué son y por qué son importantes?
• Planes para habilitar múltiples afirmaciones en el ORCID Registro

ORCID los miembros pueden actualizar la información que han agregado previamente a un ORCID registro. Solo se puede actualizar un elemento a la vez, y solo se puede actualizar con las credenciales del cliente que lo creó en primer lugar.

Para facilitar la actualización, asegúrese de almacenar el código de acceso y el token de acceso al crear elementos.

Dar formato al elemento actualizado in ORCID esquema de mensaje con la información modificada e incluir la almacenada poner código.

<?xml version="1.0" encoding="UTF-8"?>      <employment:employment put-code="739288" [...]>     [...]            </employment:employment>

Llame a la 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

Llamadas de ejemplo: GitHub

La API devolverá un mensaje 200 OK para indicar que el artículo se actualizó correctamente. Consulte nuestra página de solución de problemas si se devuelve un mensaje diferente.

Todos los elementos (excepto el texto de la biografía) en un ORCID registro tiene un poner 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 de transferencia se puede utilizar para realizar una llamada a la API para recuperar los datos completos de un artículo. Los siguientes elementos se pueden consultar utilizando un poner código:

Usando el punto final de la sección y el código de colocación, puede llamar a la API usando su mismo token de acceso para obtener ese elemento específico en su totalidad. Esta llamada de ejemplo recupera el elemento de financiación completo 4413 en formato XML utilizando la API de miembro en el servidor de espacio aislado.

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

Llamada de ejemplo: GitHub

La API devolverá un mensaje 200 OK para indicar que el mensaje se recibió correctamente y devolverá el XML completo del elemento de financiación:

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

Puede comprobar el fuente de un artículo al leerlo si quieres saber quién lo agregó.

Si ha agregado datos que deben eliminarse, por ejemplo, si se han asociado con el ORCID iD, entonces puede realizar una solicitud HTTP DELETE especificando el punto final relevante, junto con la ORCID identificación, token de acceso almacenado y código put almacenado. Solo se puede eliminar un elemento a la vez, y solo puede eliminar elementos agregados por su cliente. Puede eliminar elementos incluso cuando el usuario haya revocado el permiso.

Esta llamada de ejemplo elimina el elemento de empleo con el código de colocación "739288" de un 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

Llamada de ejemplo: GitHub

Consulta nuestra lista de identificadores admitidos para la API V3.0. Ocasionalmente agregamos nuevos tipos a pedido de ORCID miembros que deseen utilizarlos al agregar elementos al registro.

ORCID apoya el uso de  Identificadores ROR, Identificadores GRID y Registro de financiadores de Crossref identificadores para eliminar la ambigüedad de las organizaciones en ORCID Records. 

Para más información, consulte la Trabajar con identificadores de organización

Aunque los identificadores Ringgold todavía existen dentro del ORCID registro, a partir del 1 de agosto de 2023, ORCID ya no recibe actualizaciones de la base de datos de identificadores de organizaciones RINGGOLD utilizada por nuestro Registro, ni podremos procesar ni utilizar los ID de RINGGOLD creados después de esa fecha. Vea nuestro Preguntas Frecuentes para más información

Trabaja en ORCID se agrupan según sus identificadores y la relación de esos identificadores con la obra. Hay cuatro tipos de relaciones:

• Propia: el identificador se refiere únicamente a esa obra y se puede agrupar con otras obras que tengan el mismo identificador
• Parte de: la obra forma parte de este identificador y no se puede agrupar con otras obras
• La versión de: estos identificadores se aplican a versiones alternativas del trabajo y se pueden agrupar con uno mismo y con la versión de los identificadores
• Fundado por: estos identificadores se aplican a la financiación del trabajo. Estos identificadores no se utilizan para agrupar obras.

Nuestra API proporciona soporte para esto en XSD. Cada elemento tiene un atributo de índice de visualización que indica su clasificación dentro de su grupo. El índice de visualización más alto es el elemento preferido seleccionado por el investigador. Los elementos agregados a través de la API que no han sido clasificados por el investigador tienen un índice de visualización de 1 y se utilizan como fuente preferida predeterminada dentro del grupo hasta que el investigador los cambie. El índice de visualización también determina la orden de trabajo al leer el ORCID registrar con la API.

Para obtener más información sobre la agrupación en ORCID registros, consulte nuestro Artículo de apoyo.

La visibilidad indica la configuración de privacidad del elemento, según la preferencia de visibilidad establecida por el usuario. Si se incluye una etiqueta de visibilidad cuando se publica información a través de la API, se ignorará. Por el contrario, la información se publicará según la preferencia de visibilidad predeterminada del usuario según lo establecido en las preferencias de su cuenta.

Cualquiera puede leer los elementos públicos a través de la API y se muestran en el registro público del investigador. Los elementos de partes de confianza solo se devuelven a través de la API a los clientes que tienen acceso de lectura limitado; no están en el registro público del investigador. Los elementos privados son visibles solo para el investigador y la fuente del elemento; los únicos elementos privados devueltos a través de la API son aquellos que se agregaron al registro a través de su integración. Más sobre la configuración de visibilidad en el ORCID Registro.

Reciben una notificación en su ORCID inbox. Siempre que haya un cambio en los datos de un ORCID registro, el usuario recibe una notificación con información básica sobre el cambio, incluido el nombre del cliente que realiza la actualización, la fecha del cambio y el elemento en el ORCID registro que se actualizó. Ver nuestro Base de conocimientos del usuario para obtener más información sobre las notificaciones..  

ORCID Los registros en la caja de arena también tienen bandejas de entrada en funcionamiento. Recomendamos revisar regularmente las bandejas de entrada de sus pruebas. ORCID registros al planificar cómo sus sistemas programarán actualizaciones de datos.