Учебное пособие по API: добавление и обновление данных на ORCID запись

Вы можете запросить учетные данные API участника тестовой среды для создания и тестирования вашего приложения. Эти учетные данные позволяют вам выполнять вызовы API-интерфейса премиум-члена песочницы для чтения, записи и обновления. ORCID записи. Доступ к тестовой среде "песочницы" доступен каждому, даже если вы не являетесь ORCID членская организация.

Внимание: Если вы используете ORCID сертифицированная система поставщика услуг, которая уже поддерживает ORCID, вам не нужно регистрироваться для получения учетных данных API песочницы, если вы не хотите опробовать ORCID функциональность интеграции в среде Sandbox. 

Песочница позволяет вам создавать тестовые учетные записи пользователей и развивать свою интеграцию, не беспокоясь о влиянии данных на живые (производственные) ORCID Реестр. Песочница ведет себя так же, как и продакшн. ORCID Реестр с несколько исключений.

Создание тестовой учетной записи

Чтобы проверить ORCID API и вызовы API, такие как чтение и добавление информации в ORCID запись, вам также потребуется создать тест ORCID запись в песочнице. Это можно сделать через пользовательский интерфейс, как на продакшене. ORCID Реестр. Перейти к https://sandbox.orcid.org/register и зарегистрируйте аккаунт.

Адреса электронной почты Mailinator

Сервер песочницы отправляет электронные письма только на Mailinator Адреса электронной почты (@mailinator.com), чтобы непреднамеренно не спамить почтовые серверы. Вы не получите электронное письмо с подтверждением или уведомление о сбросе пароля, если не используете адрес @mailinator.com, а проверка требуется для внесения любых изменений в записи песочницы вручную. Узнайте больше об их бесплатных общедоступных почтовых ящиках здесь. Если вы не хотите использовать Mailinator адрес, затем запишите свое имя пользователя и пароль (поскольку вы будете использовать их для авторизации вашего приложения при тестировании) и свяжитесь с нами, чтобы запросить помощь с проверкой.

Mailinator это служба электронной почты, которая имеет общедоступную бесплатную услугу и частную платную услугу. Для тестирования вы можете воспользоваться совершенно бесплатным публичным сервисом. Узнайте больше об их уровнях здесь.

Mailinator - это сторонний сервис, который не управляется и не поддерживается ORCID. Мы рекомендуем вам ознакомиться с принципами работы этой службы и ее ограничениями, прежде чем использовать эти адреса.

Существует два разных объема обновлений: один для биографических данных, а другой - для мероприятий.

ORCID интеграции используют «трехсторонний OAuth» для аутентификации пользователей и запроса разрешения на взаимодействие с их записями. Любая интеграция может запрашивать разрешения на чтение с помощью общедоступного API. ORCID участники могут использовать Member API для запроса разрешений на обновление. Это работает следующим образом:

• Вы создаете специальную ссылку
• При нажатии пользователь отправляется на ORCID
  • ORCID просит пользователя войти в систему
  • ORCID просит пользователя предоставить разрешение вашему приложению
  • ORCID отправляет пользователя обратно в вашу систему с кодом авторизации
• Ваша система обменивает этот код на токен доступа

Настраиваемый URL-адрес авторизации включает информацию о вашем клиенте, а также «области действия», которые определяют определенные области их записи, к которым вы хотите получить доступ. После входа пользователь разрешает подключение к вашей системе и возвращается на вашу целевую страницу вместе с кодом авторизации. Затем этот код используется для получения их ORCID iD вместе с токеном доступа, действительным для запрошенных областей.

Создайте ссылку для авторизации и получите код авторизации

Вы создаете ссылку авторизации, указывая идентификатор клиента учетных данных API и связанную целевую страницу (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 лет после выпуска. Токен можно использовать несколько раз до истечения срока его действия.

Используйте токен доступа

Токены трехстороннего доступа связаны с конкретными ORCID записывать. Чтобы использовать их, вы включаете их в запросы API, которые вы делаете для чтения или обновления этой записи.

При запросе разрешения на взаимодействие с ORCID запись пользователя, вы указываете одну или несколько «областей». Каждая область позволяет вам делать определенные вещи, например, читать запись или обновлять определенный раздел.

Трехсторонние (код авторизации) области

3 ножка относится к трем участникам, участвующим в получении разрешения от пользователя; ORCID, ваша система и сам пользователь.

/ аутентифицировать

Этот объем используется для сбора ORCID iD и читать общедоступную информацию только в записи. Все остальные трехсторонние области включают разрешение проверки подлинности, поэтому эту область можно не указывать при запросе любого другого доступа. Эта область доступна в членском или общедоступном API.

/ read-limited (только для API участников)

Эта область используется для получения доступа к общедоступным элементам и элементам с ограниченной видимостью на ORCID записывать. Эта область доступна только в API участников.

/ activity / update (только для API участников)

Эта область используется для записи, обновления и удаления элементов в разделах «Аффилиация», «Финансирование», «Работы», «Профессиональная деятельность», «Исследовательские ресурсы» и «Рецензирование». ORCID записывать. Эта область доступна только в API участников.

/ person / update (только для API участников)

Эта область используется для записи, обновления и удаления элементов в разделах записи, посвященных другим именам, ключевым словам, странам, URL-адресам исследователей, веб-сайтам и личным внешним идентификаторам. Эта область доступна только в API участников.

OpenID

Эта область используется интеграторами OpenID, когда требуется id_token. Когда область openid включена, реестр вернет id_token внутри ответа токена и предоставит клиенту разрешение на доступ к конечной точке информации о пользователе для этого пользователя. Эта область доступна в общедоступном и членском API.

Обратите внимание, что область «openid» не начинается с символа «/», как другие. ORCID Области API. Это связано с тем, что область действия openid не определяется ORCID, но вместо этого определяется спецификацией OpenID Connect. Пожалуйста, посмотрите наш Документация OpenID чтобы получить больше информации.

Несколько областей

За одно взаимодействие можно запросить несколько областей, перечислив области в URL-адресе аутентификации с закодированным пространством между ними, например scope = / read-limited% 20 / activity / update% 20 / person / update.

Полный доступ

Если вам нужен полный доступ для чтения и редактирования записи, включите в свой URL аутентификации три области: / read-limited, / activity / update и / person / update. В URL-адресе они будут отображаться как scope = / read-limited% 20 / activity / update% 20 / person / update.

Двухсторонние (учетные данные клиента) области

Для некоторых действий вам не нужно спрашивать разрешения у пользователя. Две области действия OAuth запрашиваются непосредственно из ORCID API и не требуют разрешения исследователя. Токены с такими областями действия действительны в течение 20 лет и могут быть использованы повторно.

/ read-public

Эта область используется для чтения общедоступной информации на одном ORCID ID, найти ORCID записи или для чтения сводной информации (только API-члены). Эта область доступна в членском или общедоступном API.

/ webhook

Эта область позволяет клиентскому приложению регистрировать веб-перехватчик на ORCID запись, чтобы получать уведомления при обновлении записи. Этот прицел доступен для премиум-класса. ORCID только для членов.

Элементы (работы, трудоустройство, финансирование, экспертная оценка и т. Д.) Могут быть добавлены в ORCID запись с использованием ORCID член API. Для этого необходимо сначала получить разрешение исследователя с помощью OAuth и форматировать метаданные элемента используя ORCID схема сообщения.

После того, как вы отформатировали данные и собрали ORCID iD и токен доступа, вы делаете запрос API с помощью HTTP POST, указывая соответствующая конечная точка.

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. Исследователь взаимодействует с Системой А ( утверждение происхождения), который использует услуги, предоставляемые Системой B, для обновления ORCID записей, что делает Систему B источник

Мы призываем наше сообщество принять участие в принятии мер по сохранению и обмену информацией о происхождении утверждений, чтобы каждый мог получить пользу от просмотра источника.

Для получения дополнительной информации, пожалуйста, см.:

• Пути обеспечения уверенности: что это такое и почему они имеют значение?
• Планы по включению нескольких утверждений в 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 для получения полных данных для элемента. Следующие элементы можно запросить с помощью поставить код:

Используя конечную точку раздела и поместив код, вы можете вызвать API, используя тот же токен доступа, чтобы получить этот конкретный элемент полностью. Этот пример вызова извлекает полную статью финансирования 4413 в формате XML с помощью API-интерфейса участника на сервере песочницы.

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 iD, то вы можете сделать 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

Пожалуйста, ознакомьтесь с нашим список поддерживаемых идентификаторов для API V3.0. Время от времени мы добавляем новые типы по запросу ORCID участники, которые хотели бы использовать их при добавлении элементов в реестр.

ORCID поддерживает использование  Идентификаторы ROR, Идентификаторы GRID и Реестр Crossref Funder идентификаторы для устранения неоднозначности организаций в ORCID Records. 

Для получения дополнительной информации см. Работа с идентификаторами организации

Хотя идентификаторы Ринггольда все еще существуют в ORCID реестр, по состоянию на 1 августа 2023 г., ORCID больше не получает обновлений базы данных идентификаторов организаций RINGGOLD, используемой нашим реестром, и мы не сможем обрабатывать или использовать идентификаторы RINGGOLD, созданные после этой даты. Посмотрите наш FAQ для получения дополнительной информации

Работает в ORCID сгруппированы вместе на основе как их идентификаторов, так и отношения этих идентификаторов к произведению. Существует четыре типа отношений:

• Сам: идентификатор относится исключительно к этой работе и может быть сгруппирован с другими произведениями, имеющими такой же идентификатор.
• Часть: произведение является частью этого идентификатора и не может быть сгруппировано с другими произведениями.
• Версия: эти идентификаторы применяются к альтернативным версиям произведения и могут быть сгруппированы с собственными идентификаторами и версиями.
• Спонсируемый: эти идентификаторы относятся к финансированию работы. Эти идентификаторы не используются для группировки работ.

Наш API обеспечивает поддержку этого в XSD. Каждый элемент имеет атрибут индекса отображения, который указывает его ранг в группе. Самый высокий показатель отображения — это предпочтительный элемент, выбранный исследователем. Элементы, добавленные через API, которые не были оценены исследователем, имеют индекс отображения 1 и используются в качестве предпочтительного источника по умолчанию в группе до тех пор, пока не будут изменены исследователем. Индекс дисплея также определяет порядок работы при чтении ORCID запись с помощью API.

Для получения дополнительной информации о группировке по ORCID записи, пожалуйста, посмотрите наши вспомогательная статья.

Видимость указывает настройку конфиденциальности элемента, основанную на настройках видимости, заданных пользователем. Если тег видимости включен при публикации информации через API, он будет проигнорирован. Скорее, информация будет публиковаться в соответствии с настройками видимости пользователя по умолчанию, установленными в настройках его учетной записи.

Публичные элементы могут быть прочитаны кем угодно через API и отображаются в общедоступной записи исследователя. Элементы доверенной стороны возвращаются через API только клиентам, имеющим доступ с ограничением чтения; они не находятся в открытом доступе исследователя. Частные элементы видны только исследователю и источнику элемента — единственные частные элементы, возвращаемые через API, — это те, которые были добавлены в запись через вашу интеграцию. Подробнее о настройках видимости в ORCID реестра.

Они получают уведомление в своем ORCID входящие. Всякий раз, когда есть изменение данных на ORCID запись, пользователь получает уведомление с базовой информацией об изменении, включая имя клиента, выполняющего обновление, дату изменения и элемент в ORCID запись, которая была обновлена. Смотрите наши База знаний пользователя для получения дополнительной информации об уведомлениях.  

ORCID записи в песочнице также есть функционирующие почтовые ящики. Мы рекомендуем регулярно просматривать почтовые ящики вашего тестирования. ORCID записи при планировании того, как ваши системы будут планировать обновления данных.