Tutkimustietovarannon lukurajapinnan käyttö

Tälle sivulle kootaan tietoa ja ohjeita tutkimustietovarannon lukurajapinnan käytöstä.

HUOM! Tunnistautumispalvelimen URL-osoite muuttunut keskiviikkoaamuna 19.6.2024 klo 9:00

"researchfi-auth.rahtiapp.fi" => "researchfi-auth.2.rahtiapp.fi"

Tiedot ovat saatavissa JSON-muodossa rajapinnasta haettuna. Tiedot noudattavat tutkimustietovarannon tietomallia ja käytössä olevia koodistoja.

Rajapinnasta saatavat tiedot päivittyvät kerran vuorokaudessa.

Yleistä rajapinnan tunnistautumisesta

Rajapinta koostuu useasta REST-endpointista, joiden autentikointi ja autorisointi on toteutettu OAuth2-protokollalla.

Käyttäjä tunnistautuu rajapintaan OAuthin Client Credentials-menetelmällä. Käyttäjä hakee ensin omalla ClientId- ja Secret -yhdistelmällään rajapinnan käyttöön tarvitun Access Tokenin ja liittää sen mukaan varsinaiseen rajapintakutsuun.

Rajapinnan osoitteet

Rajapinnan Swagger-dokumentaatio löytyy osoitteesta https://research.fi/api/rest/swagger/index.html

OAuth-palvelu

• 19.6.2024 klo 9:00 alkaen
  • Metatiedot https://researchfi-auth.2.rahtiapp.fi/realms/publicapi/.well-known/openid-configuration
  • Token-endpoint https://researchfi-auth.2.rahtiapp.fi/realms/publicapi/protocol/openid-connect/token
• Aiemmin
  • Metatiedot https://researchfi-auth.rahtiapp.fi/realms/publicapi/.well-known/openid-configuration
  • Token-endpoint https://researchfi-auth.rahtiapp.fi/realms/publicapi/protocol/openid-connect/token

Rajapinnan käyttö Swagger-sivun kautta

Rajapinnan Swagger-dokumentaatio löytyy osoitteesta https://research.fi/api/rest/swagger/index.html

Swagger-sivulta voi tutustua rajapinnan tarjoamiin sisältöihin sekä suorittaa kutsuja rajapintaan.

Tunnistautuminen Swagger-sivulla

Sivun oikeassa yläkulmassa on vihreä Authorize-painike jota klikkaamalla voidaan syöttää ClientID ja ClientSecret rajapinnan testaamista varten. Ennen kirjautumista Swaggerin lukko-kuvakkeet ovat avoimina.

Saat ClientID ja ClientSecret -tunnukset sähköpostitse tutkimustietovarantotiimiltä rekisterinpitäjän myönnettyä käyttöluvan.

Kutsujen tekeminen rajapintaan Swagger-sivulla

Tietojen syöttämisen jälkeen Swagger-sivulla voi tehdä kutsuja rajapintaan. Onnistuneen kirjautumisen jälkeen Swaggerin lukko-kuvakkeet ovat suljettuina.

Access Tokenin käyttö sovelluksissa

Access Tokenin haku

Rajapinnan käyttöön vaadittava Access token haetaan käyttäen ClientID:tä ja ClientSecretiä OAuth-palvelun Token-osoitteesta https://researchfi-auth.2.rahtiapp.fi/realms/publicapi/protocol/openid-connect/token POST-kutsulla.

Saat ClientID ja ClientSecret -tunnukset sähköpostitse tutkimustietovarantotiimiltä rekisterinpitäjän myönnettyä käyttöluvan.

Kutsun sisältöön annettavat tiedot ovat:

Esimerkkikutsussa kohdat <clientId< ja <secret> korvataan käyttäjän oikealla ClientId:llä ja ClientSecretillä.

Esimerkkikutsu Curl-ohjelmalla

Onnistunut kutsu palauttaa Access Tokenin osana vastausta.

Esimerkkivastaus

Access Tokenin lisääminen rajapintakutsuun

Varsinaiseen rajapintakutsuun Access Token lisätään Authorization-headeriin muodossa "Bearer <authenticationToken>".

Esimerkkikutsu access tokenin käytöstä

Access Tokenin voimassaolo

Access Token on voimassa 90 vuorokautta sen luomisajankohdasta. Uuden Access Tokenin voi luoda kohdan "Access Tokenin haku" mukaisesti jo ennen umpeutumisajankohtaa.

Export-endpointtien käyttö

Endpointit

• /v1/funding-calls-export
• /v1/funding-decisions-export
• /v1/publications-export
• /v1/research-datasets-export

Toimintaperiaate

Export-endpointit mahdollistavat koko API-datan hakemisen, eikä niissä ole 10000 tuloksen rajoitetta, kuten tavallisissa endpointeissa. Datan haku tehdään toistamalla API-kutsuja samoilla hakuparametreilla, kunnes rajapinta ei enää palauta tuloksia.

Tärkeää:

Normaalien parametrien lisäksi hakuun on annettava parametri NextPageToken, joka ohjaa taustajärjestelmän hakutulosten sivutusta. Parametrin arvo otetaan talteen edellisen haun vastaussanoman otsikosta (HTTP headers) x-next-page-token.

Python esimerkkikoodi

Kuvaus

Allaoleva Python-ohjelma havainnollistaa datan hakua NextPageToken-parametrin avulla.

• Ohjelma
  • Tunnistautuu rajapinnan käyttäjäksi (client_id / client_secret)
  • Hakee organisaatiotunnuksen '01901' julkaisut export-endpointista (/v1/publications-export)
  • Tulostaa julkaisujen nimet

Ohjelmakoodi

import requests
import sys
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

# API credentials
client_id = 'myclientid'
client_secret = 'mysecretapikey'

# API endpoint
api_url = 'https://research.fi/api/rest/v1/publications-export'

# Get API access token
token_url = 'https://researchfi-auth.2.rahtiapp.fi/realms/publicapi/protocol/openid-connect/token'
client = BackendApplicationClient(client_id=client_id)
oauth = OAuth2Session(client=client)
try:
    token = oauth.fetch_token(
        token_url=token_url, client_id=client_id, client_secret=client_secret)
except Exception as ex:
    print(ex)
    sys.exit(1)

# Get data from API
counter = 1
next_page_token = 0
while (counter <= 200000):
    # Query parameters.
    # MUST:
    #   - Include NextPageToken, which was provided in the previous HTTP response headers
    #   - Keep the other parameters unchanged
    query_parameters = {
        'OrganizationId': '01901',
        'PageSize': 1000,
        'NextPageToken': next_page_token
    }

    # API request
    try:
        response = oauth.get(api_url, params=query_parameters)
        response.raise_for_status()
    except Exception as ex:
        # Exit in case of API error
        print(ex)
        sys.exit(1)
    if len(response.json()) == 0:
        # Exit if there are no more results
        sys.exit(0)

    # Process API response data
    for publication in response.json():
        print(str(counter) + ": " +
              publication['id'] + ": " + publication['name'])
        counter += 1

    # Store token, use it in the next query to get more results
    next_page_token = response.headers['x-next-page-token']

Python esimerkkiohjelman riippuvuudet

Edellä kuvattu esimerkki vaatii toimiakseen Python-kirjastot:

certifi==2024.8.30
charset-normalizer==3.4.0
idna==3.10
oauthlib==3.2.2
requests==2.32.3
requests-oauthlib==2.0.0
urllib3==2.2.3

Virta-julkaisutietopalvelun raporttien hyödyntäminen

Virta-julkaisutietopalvelun virhe-, duplikaatti-, yhteisjulkaisujen ristiriitaisuudet - ja tilanneraportteja hyödynnetään tutkimustietovarannon rajapintakokonaisuuden kautta. Raporttirajapinnat ovat käytettävissä kaikilla organisaatioilla, jotka hyödyntävät julkaisujen tietoja.

Erot aiemmin käytössä olleisiin Virta-julkaisutietopalvelun omiin rajapintoihin:

Duplikaatit

Tilanne

Virheet

 Ristiriitaiset