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

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

• Войдите в свой ORCID запись:
  Производственный сервер: https://orcid.org/signin
  Сервер тестирования песочницы: https://sandbox.orcid.org/signin
• Нажмите на свое имя в правом верхнем углу.
• Нажмите Инструменты разработчика из пункта меню
  Примечание: Чтобы получить доступ к инструментам разработчика, вы должны подтвердить свой адрес электронной почты. Если вы еще не подтвердили свой адрес электронной почты, вам будет предложено сделать это, прежде чем вы сможете зарегистрироваться для получения учетных данных общедоступного API.
• Прочитайте и согласитесь с 'ORCID Условия обслуживания публичных клиентов
• Нажмите «Зарегистрироваться для ORCID общедоступные учетные данные API».

Заполнение формы сведений о заявке

• После того, как вы зарегистрируетесь для получения учетных данных Public API, вы будете перенаправлены обратно в Инструменты разработчика (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• Вам необходимо заполнить форму сведений о заявке, представленную для регистрации новой заявки.
  • Имя: Имя вашего приложения. Это будет показано пользователям, когда они предоставят вашему приложению разрешение на получение своих ORCID iD, и он будет отображаться в их Список доверенных организаций. Мы рекомендуем использовать название вашей организации или службы (например, название журнала).
  • URL приложения: Веб-сайт, который пользователь может посетить, чтобы узнать больше о вашем приложении. Это также будет отображаться в их Список доверенных организаций.
  • Описание приложения: Информация о приложении, которое вы разрабатываете, и о том, как вы будете использовать пользовательский ORCID я бы. Это будет отображаться для пользователей на экране OAuth.

Добавление Перенаправить URI

Как только пользователь авторизует ваше приложение, он будет возвращен на указанный вами URI. Вы должны указать эти URI заранее, иначе ваши пользователи интеграции столкнутся с ошибкой.

• Введите свой URI перенаправления в соответствующее поле.
• Если вам нужно ввести более 1 URI перенаправления, нажмите «Добавить другой URI перенаправления».

Пожалуйста, обратите внимание:

• Только URI HTTPS принимаются в производство
• Домены зарегистрированы ДОЛЖЕН точно соответствуют используемым доменам, включая субдомены
• Зарегистрируйте все URI перенаправления полностью, где это возможно. Это самый безопасный вариант, который мы рекомендуем. Для получения дополнительной информации об URI перенаправления см. часто задаваемые вопросы по URI перенаправления

Сохранение вашего приложения

После того, как вы заполнили форму заявки и добавили свои URI перенаправления, вы можете сохранить свое приложение.

• Нажмите «Сохранить мое приложение и создать мой клиент». ID и секрет'

Вы будете перенаправлены обратно на страницу инструментов разработчика, которая теперь будет включать ваши учетные данные клиента Public API.

Обновление ваших учетных данных

Внести изменения в информацию о приложении очень просто.

• Отредактируйте соответствующую информацию и нажмите «Сохранить приложение».

Используйте свои учетные данные

Теперь, когда у вас есть учетные данные, пора начать использовать ORCID Публичный API!

Обратите внимание, что мы можем передать ваши учетные данные членскому API, если вы станете ORCID член в будущем.

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

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

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

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

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

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

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

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

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

Любой человек с общедоступными учетными данными или учетными данными API может получить / read-public токен доступа. Чтобы получить токен, вы звоните в ORCID Конечная точка токена API.

Этот процесс часто называют потоком OAuth для учетных данных клиента или двухэтапным OAuth.

Пример вызова для получения токена доступа для чтения общедоступных данных в песочнице - замените заполнители своими учетными данными (обязательно удалите скобки.

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

Затем вам будет возвращен токен доступа, подобный приведенному ниже. Возвращенный токен является долгоживущим (не истекает примерно 20 лет) и может использоваться несколько раз для получения общедоступных данных из ORCID Records. 

{"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}

записки: Все токены с областью / Authenticate теперь также имеют область / read-public. Если вы используете только область / Authenticate, вы можете использовать сохраненные токены доступа для чтения общедоступных данных без необходимости повторного получения токена доступа. 

Чтобы получить / ограниченный доступ для чтения, вы должны спросить разрешения у исследователя. Вы делаете это с помощью OAuth. Конкретно, "Трехсторонний OAuth».

Для получения дополнительной информации, пожалуйста, посетите наш Учебное пособие по API: чтение данных на ORCID запись

ORCID интеграции используют «трехсторонний OAuth» для аутентификации пользователей и запроса разрешения на взаимодействие с их записями. Любая интеграция может запрашивать разрешения на чтение с помощью общедоступного API. ORCID участники могут использовать Member 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 лет после выпуска. Токен можно использовать несколько раз до истечения срока его действия.

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

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

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

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

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

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

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>

Каждый элемент (работа, финансирование, занятость и т. Д.) Имеет поставить код. При необходимости его можно использовать для получения полной информации об элементе.

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

Таблица сводных разделов, для чтения которых вы можете использовать API, приведена ниже.

Все предметы (кроме текста биографии) на 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 сгруппированы вместе на основе как их идентификаторов, так и отношения этих идентификаторов к произведению. Существует четыре типа отношений:

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

Наш API поддерживает это в XSD. Каждый элемент имеет атрибут индекса отображения, который указывает его ранг в группе. Наивысший индекс отображения - это предпочтительный элемент, выбранный исследователем, элементы, добавленные через API, которые не были ранжированы исследователем, имеют индекс отображения 0. Индекс отображения также определяет порядок работы при чтении ORCID записи.

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

Эпоха ORCID Реестр поддерживает «согласование содержимого». Это означает, что машины и другие системы могут запрашивать ORCID реестр метаданных человека в разных форматах.

Одним из таких форматов является JSON-LD, в котором используется schema.org словарный запас, в частности Тип человека, которые мы связываем с работами, организациями и другими идентификаторами. Мы также поддерживаем XML, JSON, RDF XML и turtle, а также реализовали совместное использование ресурсов между источниками (CORS), чтобы упростить доступ к нашим данным.

• См. этот сообщение в блоге с обзором ORCID и schema.org
• Смотрите наши техническая документация по согласованию контента

Поиск пользователя с помощью cURL:

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

Вернет 200, даже если пользователь не существовать. Чтобы этого избежать, используйте в вызове согласование содержимого следующим образом:

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