API 자습서 : 데이터 추가 및 업데이트 ORCID 기록

여러분의 시간과 재능으로 샌드 박스 멤버 API 자격 증명 요청 애플리케이션을 구축하고 테스트합니다. 이러한 자격 증명을 사용하면 샌드박스 프리미엄 회원 API를 호출하여 읽고, 쓰고, 업데이트할 수 있습니다. ORCID 기록. 샌드 박스 테스트 환경에 대한 액세스는 사용자가 아니더라도 누구나 무료로 사용할 수 있습니다. ORCID 회원 조직.

주의 사항: 다음을 사용하는 경우 ORCID 이미 지원하고 있는 인증된 서비스 제공업체 시스템 ORCID, 샌드박스 API 자격 증명을 시험해 보기를 원하지 않는 한 등록할 필요가 없습니다. ORCID 샌드박스 환경 내 통합 기능. 

샌드 박스를 사용하면 라이브 (프로덕션) 데이터에 영향을주지 않고 테스트 사용자 계정을 만들고 통합을 개발할 수 있습니다. ORCID 기재. 샌드 박스는 프로덕션과 동일한 방식으로 작동합니다. ORCID 레지스트리 몇 가지 예외.

테스트 계정 만들기

테스트하기 위해 ORCID API 및 API 호출(예: 정보 읽기 및 추가) ORCID 기록하려면 테스트도 만들어야합니다. ORCID 샌드 박스에 기록합니다. 이는 프로덕션에서와 같이 사용자 인터페이스를 통해 수행 할 수 있습니다. ORCID 기재. 이동 https://sandbox.orcid.org/register 계정을 등록하십시오.

우편물 이메일 주소

샌드박스 서버는 다음 사용자에게만 이메일을 보냅니다. 메일 레이터 (@mailinator.com) 메일 서버에 실수로 스팸 메일을 보내지 않도록 이메일 주소. @mailinator.com 주소를 사용하지 않으면 확인 이메일이나 비밀번호 재설정 알림을 받지 못하며 샌드박스 레코드를 수동으로 편집하려면 확인이 필요합니다. 무료 공개 받은편지함에 대해 자세히 알아보기 여기를 클릭해 문의해주세요. 사용을 원하지 않으시면 메일 레이터 주소를 입력한 다음 사용자 이름과 비밀번호를 기록하고(테스트할 때 애플리케이션에 권한을 부여하는 데 사용하므로) 당사에 연락하여 확인 지원을 요청하십시오.

메일 레이터 는 공개 무료 서비스와 비공개 유료 서비스가 있는 이메일 서비스입니다. 테스트를 위해 완전 무료 공공 서비스를 사용할 수 있습니다. 등급에 대해 자세히 알아보기 LINK.

Mailinator는 ORCID. 이러한 주소를 사용하기 전에이 서비스의 작동 방식과 제한 사항을 검토하는 것이 좋습니다.

두 가지 다른 업데이트 범위가 있습니다. 하나는 전기 정보 용이고 다른 하나는 활동 용입니다.

ORCID 통합은 "3 legged OAuth"를 사용하여 사용자를 인증하고 레코드와 상호 작용할 수 있는 권한을 요청합니다. 모든 통합은 공개 API를 사용하여 읽기 권한을 요청할 수 있습니다. ORCID 회원은 회원 API를 사용하여 업데이트 권한을 요청할 수 있습니다. 다음과 같이 작동합니다.

• 특별한 링크를 만듭니다.
• 클릭하면 사용자가 ORCID
  • ORCID 사용자에게 로그인을 요청합니다.
  • ORCID 사용자에게 애플리케이션에 대한 권한 부여를 요청합니다.
  • ORCID 사용자를 인증 코드와 함께 시스템으로 다시 보냅니다.
• 시스템은 해당 코드를 액세스 토큰으로 교환합니다.

사용자 정의된 승인 URL에는 귀하의 클라이언트 정보뿐만 아니라 귀하가 액세스하려는 기록의 특정 영역을 지정하는 '범위'도 포함됩니다. 로그인한 후 사용자는 시스템 연결을 승인하고 인증 코드와 함께 랜딩 페이지로 돌아갑니다. 그런 다음 이 코드를 사용하여 ORCID iD 요청된 범위에 유효한 액세스 토큰과 함께.

인증 링크를 만들고 인증 코드를 가져옵니다.

API 자격 증명의 클라이언트 ID와 관련 랜딩 페이지(리디렉션 URI)를 지정하여 권한 부여 링크를 빌드합니다. 요청할 권한을 설정하여 선택합니다. 범위 매개 변수.

아래 예제는 액세스가 제한된 데이터를 읽을 수있는 권한을 요청합니다. ORCID 샌드박스 테스트 서버. 실제로는 이 링크를 웹사이트에 표시하거나 사용자에게 인증 및 권한 부여를 요청할 때 이메일에 포함시킵니다. 그러나 테스트 목적으로 간단히 웹 브라우저에 붙여넣을 수 있습니다. 괄호 안의 데이터를 고객 정보로 바꾸고 대괄호를 제거하세요!

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

사용자가 링크를 클릭하고 로그인 한 경우 ORCID 부여 된 권한은 다음과 같이 사이트로 다시 리디렉션됩니다.

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

승인 코드를 ORCID iD 및 액세스 토큰

즉시 승인 코드를 교환해야합니다. ORCID iD 및 액세스 토큰. 인증 코드는 사용 시 만료됩니다. 요청은 다음과 같습니다. 웹 브라우저에서 만들 수 없습니다, 서버에서 만들어야합니다.

 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 그런 다음 연구원의 인증을 반환합니다 ORCID iD 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"}

액세스 토큰은 기본적으로 오래 사용되며 발행 후 20 년이 지나면 만료됩니다. 토큰은 만료되기 전에 여러 번 사용할 수 있습니다.

액세스 토큰 사용

3-legged 액세스 토큰은 특정 ORCID 기록. 이를 사용하려면 해당 레코드를 읽거나 업데이트하기 위해 수행하는 API 요청에 이를 포함시킵니다.

상호 작용 권한을 요청할 때 ORCID 사용자 레코드에 하나 이상의 '범위'를 지정합니다. 각 범위를 사용하면 레코드 읽기 또는 특정 섹션 업데이트와 같은 특정 작업을 수행할 수 있습니다.

3-legged (인증 코드) 범위

3 다리 사용자로부터 허가를 얻는 데 관여하는 세 명의 행위자를 의미합니다. ORCID, 시스템 및 사용자 자신.

/ 인증

이 범위는 ORCID iD 기록에 있는 공개 정보만 읽으십시오. 다른 모든 3-legged 범위에는 인증 권한이 포함되어 있으므로 다른 액세스를 요청하는 경우 이 범위를 생략할 수 있습니다. 이 범위는 Member 또는 Public API에서 사용할 수 있습니다.

/ read-limited (멤버 API 전용)

이 범위는 공개 및 제한된 가시성 항목을 읽기 위해 액세스하는 데 사용됩니다. ORCID 기록. 이 범위는 Member API에서만 사용할 수 있습니다.

/ activities / update (멤버 API 만 해당)

이 범위는 소속, 자금 조달, 작업, 전문 활동, 연구 리소스 및 동료 검토 섹션의 항목을 작성, 업데이트 및 삭제하는 데 사용됩니다. ORCID 기록. 이 범위는 Member API에서만 사용할 수 있습니다.

/ person / update (멤버 API 만 해당)

이 범위는 레코드의 다른 이름, 키워드, 국가, 연구원 URL, 웹 사이트 및 개인 외부 식별자 섹션에서 항목을 작성, 업데이트 및 삭제하는 데 사용됩니다. 이 범위는 Member API에서만 사용할 수 있습니다.

openid

이 범위는 id_token이 필요할 때 OpenID 통합자가 사용합니다. openid 범위가 포함되면 레지스트리는 토큰 응답 내에서 id_token을 반환하고 해당 사용자의 사용자 정보 끝점에 액세스 할 수있는 클라이언트 권한을 부여합니다. 이 범위는 공용 및 멤버 API에서 사용할 수 있습니다.

'openid'범위는 다른 것과 같이 '/'로 시작하지 않습니다. ORCID API 범위. 이것은 'openid'범위가 다음에 의해 정의되지 않았기 때문입니다. ORCID이지만 대신 OpenID Connect 사양에 의해 정의됩니다. 우리를 참조하십시오 OpenID 문서

여러 범위

scope = / read-limited % 20 / activities / update % 20 / person / update와 같이 각각 사이에 인코딩 된 공백을 사용하여 인증 URL에 범위를 나열하여 단일 상호 작용에서 여러 범위를 요청할 수 있습니다.

완전한 액세스

레코드를 읽고 편집하기위한 전체 액세스 권한을 원하는 경우 인증 URL에 / read-limited, / activities / update 및 / person / update의 세 가지 범위가 포함됩니다. URL에서는 scope = / read-limited % 20 / activities / update % 20 / person / update로 표시됩니다.

2-legged (클라이언트 자격 증명) 범위

일부 활동의 경우 사용자에게 권한을 요청할 필요가 없습니다. Two legged OAuth 범위는 ORCID API이며 연구원에게 허가를 요구하지 않습니다. 이러한 범위의 토큰은 20 년 동안 유효하며 재사용 할 수 있습니다.

/ 공개 읽기

이 범위는 하나의 공개 정보를 읽는 데 사용됩니다. ORCID 아이디,검색 ORCID 기록 또는 요약 정보 읽기(회원 API에만 해당) 이 범위는 회원 또는 공개 API에서 사용할 수 있습니다.

/ webhook

이 범위를 사용하면 클라이언트 애플리케이션이 웹훅을 ORCID 레코드가 업데이트 될 때 알림을 수신하기 위해. 이 범위는 프리미엄에 사용할 수 있습니다. ORCID 회원 전용.

항목 (근로, 고용, 자금 지원, 동료 검토 등)을 추가 할 수 있습니다. ORCID 사용하여 기록 ORCID 회원 API. 이렇게 하려면 먼저 OAuth를 사용하여 연구원의 허가를 얻습니다. 및 항목 메타 데이터 형식 지정 를 사용하여 ORCID 메시지 스키마.

데이터를 포맷하고 수집한 후에는 ORCID iD 액세스 토큰이 있는 경우 HTTP POST를 사용하여 API 요청을 수행하고 관련 엔드 포인트.

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

아래 호출은 새로운 고용 샌드 박스 테스트 서버의 레코드에 대한 소속 :

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

예제 호출 : Github

API는 항목과 함께 항목이 올바르게 게시되었음을 나타내는 201 메시지를 반환합니다. 코드 입력. 귀하의 클라이언트는 항목의 출처.

우리의 확인 문제 해결 다른 메시지가 반환되는 경우 페이지. 저장해야합니다.  풋 코드 및 액세스 토큰 저장 업데이트하거나 항목을 제거합니다.

An ORCID 기록에는 연구자의 작업, 소속, 자금 지원, 동료 검토 등에 대한 정보가 포함될 수 있습니다.

항목 ORCID 기록은 주장 그 연결 ORCID 활동 또는 소속이있는 ID 보유자. 이러한 주장은 ORCID 기록을 소유 한 연구원 또는 연구원이 허용 한 시스템에 의한 기록. 어설 션을 추가 한 엔티티를 ORCID 기록하다  .

예

투명성과 개방성의 원칙에 따라 주장의 출처를 볼 수있는 것이 중요하다고 믿습니다. 누가 그 정보를 기록에 추가하고 있는지 말입니다. 이를 수행하는 방법은 다음과 같습니다.

1. 연구자 (또는 대리인이 신뢰할 수있는 개인) 레코드에 주장을 추가합니다. ORCID 그 사람을 소스로 자동 기록
2. 연구자가 승인 한 시스템이 기록에 주장을 추가하면 ORCID 자동으로 시스템 소유자 ( ORCID 회원)을 출처로 합니다.

사용자 인터페이스에 소스 이름을 표시하고 API에서 고유 식별자를 사용하여 사용할 수 있도록합니다.

그러나 연구 정보 워크 플로는 이보다 더 복잡 할 수 있으며, 한 시스템이 사람 또는 다른 시스템을 대신하여 항목을 추가하면 주장의 실제 소스가 의도 치 않게 가려 질 수 있습니다. 투명성을 보장하기 위해 누가 그 사람과 항목을 연결했는지, 누가 항목을 기록에 추가했는지 구분해야합니다. 위와 같이 항목을 추가하는 사람은 ORCID 기록은  ; 누구든지 사이의 연결을 만드는 ORCID iD 그리고 항목은 주장 출처.

예 :

1. 연구원은 데이터를 자신의 ORCID 검색 및 연결 마법사와 같은 시스템에서 기록합니다. 연구자는 그들의 주장을 연결하는 주장을 하고 있다. iD 항목과 함께, 그래서 그들은 주장 출처; 시스템은 어설 션을 ORCID 기록 — 
2. 연구원이 시스템 A ( 주장 원본), 시스템 B에서 제공하는 서비스를 사용하여 업데이트 ORCID 기록, 시스템 B를 

우리는 커뮤니티가 주장 출처에 대한 정보를 보존하고 공유하는 조치를 취하여 모든 사람이 출처를 보는 것으로부터 혜택을받을 수 있도록 권장합니다.

자세한 내용은 다음을 참조하십시오 :

• Assertion Assurance Pathways : 그것들은 무엇이며 왜 중요한가?
• 여러 어설 션을 활성화하기위한 계획 ORCID 레지스트리

ORCID 회원은 이전에 추가 한 정보를 업데이트 할 수 있습니다. ORCID 기록. 한 번에 하나의 항목 만 업데이트 할 수 있으며 처음에 항목을 만든 클라이언트 자격 증명을 사용해서 만 업데이트 할 수 있습니다.

업데이트를 용이하게하려면 풋 코드 및 액세스 토큰 저장 항목을 만들 때.

업데이트 된 항목 서식 지정 in ORCID 메시지 스키마 변경된 정보와 함께 저장된 코드 입력.

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

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

예제 호출 : GitHub

API는 항목이 올바르게 업데이트되었음을 ​​나타내는 200 OK 메시지를 반환합니다. 다른 메시지가 반환되면 문제 해결 페이지를 확인하십시오.

모든 항목(전기 텍스트 제외)은 ORCID 기록은 코드 입력:

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

이 풋 코드는 항목에 대한 전체 데이터를 검색하기 위해 API를 호출하는 데 사용할 수 있습니다. 다음 항목은 a를 사용하여 쿼리 할 수 ​​있습니다. 코드 입력:

섹션 엔드 포인트 및 코드 입력을 사용하면 동일한 액세스 토큰을 사용하여 API를 호출하여 해당 특정 항목을 완전히 가져올 수 있습니다. 이 예제 호출은 샌드 박스 서버에서 멤버 API를 사용하여 XML 형식의 전체 자금 조달 항목 4413을 검색합니다.

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

예제 호출 : GitHub

API는 메시지가 성공적으로 수신되었음을 나타내는 200 OK 메시지를 반환하고 자금 조달 항목의 전체 XML을 반환합니다.

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

당신은을 확인할 수 있습니다 항목의 출처 누가 그것을 추가했는지 알고 싶다면 그것을 읽을 때.

삭제해야하는 데이터를 추가 한 경우 (예 : 잘못된 데이터와 관련된 경우) ORCID 다음을 지정하는 HTTP DELETE 요청을 만들 수 있습니다. 관련 끝점, 와 함께 ORCID 신분증, 저장된 액세스 토큰 및 저장된 풋 코드. 한 번에 하나의 항목만 삭제할 수 있으며 클라이언트가 추가한 항목만 삭제할 수 있습니다. 사용자가 권한을 철회한 경우에도 항목을 삭제할 수 있습니다.

이 예제 호출은 레코드에서 넣기 코드가 "739288"인 고용 항목을 삭제합니다. "

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

예제 호출 : GitHub

을 참조하십시오 지원되는 식별자 목록 V3.0 API용. 우리는 때때로 요청에 따라 새로운 유형을 추가합니다. ORCID 레지스트리에 항목을 추가 할 때이를 사용하려는 회원.

ORCID 사용 지원  ROR 식별자, GRID 식별자 및 Crossref Funder 레지스트리 조직을 명확하게하는 식별자 ORCID 기록. 

자세한 내용은 다음 링크를 참조하세요 조직 식별자 작업

Ringgold 식별자는 여전히 ORCID 등록부(1년 2023월 XNUMX일 기준) ORCID 더 이상 당사 레지스트리에서 사용하는 RINGGOLD 조직 식별자 데이터베이스에 대한 업데이트를 받지 않으며 해당 날짜 이후에 생성된 RINGGOLD ID를 처리하거나 사용할 수 없습니다. 우리를 참조하십시오 자주 하는 질문 자세한 정보를위한

작동 ORCID 식별자와 저작물과의 관계에 따라 함께 그룹화됩니다. 다음과 같은 네 가지 유형의 관계가 있습니다.

• 셀프: 식별자는 해당 저작물만을 지칭하며 동일한 식별자를 가진 다른 저작물과 그룹화 될 수 있습니다.
• 부분의: 저작물은이 식별자의 일부이며 다른 저작물과 그룹화 할 수 없습니다.
• 버전: 이러한 식별자는 작업의 대체 버전에 적용되며 자체 및 식별자 버전으로 그룹화 될 수 있습니다.
• 재정 지원:이 식별자는 작업 자금에 적용됩니다. 이러한 식별자는 작품을 분류하는 데 사용되지 않습니다.

우리 API는 XSD에서 이를 지원합니다. 각 항목에는 그룹 내 순위를 나타내는 표시 색인 속성이 있습니다. 가장 높은 표시 지수가 연구자가 선택한 선호 항목입니다. 연구원이 순위를 지정하지 않은 API를 통해 추가된 항목은 표시 지수 1을 가지며 연구원이 변경할 때까지 그룹 내 기본 선호 소스로 사용됩니다. 디스플레이 인덱스는 또한 읽을 때 작업 순서를 결정합니다. ORCID API로 기록하세요.

그룹화에 대한 자세한 내용은 ORCID 기록, 우리의 지원 기사.

가시성은 사용자가 설정 한 가시성 기본 설정에 따라 항목의 개인 정보 설정을 나타냅니다. API를 통해 정보를 게시 할 때 가시성 태그가 포함되면 무시됩니다. 오히려 정보는 계정 환경 설정에 설정된 사용자의 기본 공개 환경 설정에 따라 게시됩니다.

공개 항목은 API를 통해 누구나 읽을 수 있으며 연구원의 공개 기록에 표시됩니다. 신뢰할 수 있는 당사자 항목은 API를 통해 읽기 제한 액세스 권한이 있는 클라이언트에게만 반환됩니다. 연구자의 공개 기록에는 없습니다. 개인 항목은 연구원과 항목 소스만 볼 수 있습니다. API를 통해 반환되는 유일한 개인 항목은 통합을 통해 기록에 추가된 항목입니다. 가시성 설정에 대한 자세한 내용은 ORCID 레지스트리.

그들은 자신의 ORCID 받은 편지함. 데이터가 변경 될 때마다 ORCID 기록하면 사용자는 업데이트를 수행하는 클라이언트의 이름, 변경 날짜 및 해당 항목의 항목을 포함하여 변경에 대한 기본 정보가 포함 된 알림을받습니다. ORCID 갱신 된 기록. 우리를 참조하십시오 알림에 대한 자세한 내용은 사용자 기술 자료.  

ORCID 샌드 박스의 레코드도 작동하는받은 편지함. 테스트받은 편지함을 정기적으로 살펴 보는 것이 좋습니다. ORCID 시스템이 데이터 업데이트를 예약하는 방법을 계획 할 때 기록합니다.