Wikidata:Tools/OpenRefine/Editing/Tutorials/Working with APIs/nl
In deze tutorial gaan we informatie uit een web API halen en opladen naar Wikidata. Een API is een machineleesbare versie van een website, die de automatische extractie van informatie van deze website vergemakkelijkt.
Beginnen
ORCID is een initiatief om unieke identificatiegegevens te verstrekken aan wetenschappelijke auteurs. Iedereen kan zijn eigen profiel aanmaken op ORCID en een unieke identificatie krijgen die ze kunnen gebruiken bij het schrijven van onderzoeksartikelen of andere artefacten. In Wikidata kan de eigenschap ORCID iD (P496) worden gebruikt om te linken naar deze profielen, die vaak informatie bevatten over de werkgever van de onderzoeker. Op het moment van schrijven geeft Andreas Küttel (Q289574) bijvoorbeeld geen affiliatie aan, maar linkt het naar https://orcid.org/0000-0003-0235-3590 die een Employment record vermeldt. Ons doel is om deze informatie te importeren in Wikidata.
Laten we eerst een kleine SPARQL-query schrijven om voorbeelden te vinden van onderzoekers die geen enkele affiliatie hebben met hun Wikidata-item, maar wel een ORCID iD (P496).
SELECT ?researcher ?orcid WHERE {
?researcher wdt:P31 wd:Q5;
wdt:P496 ?orcid.
FILTER NOT EXISTS { ?researcher wdt:P108 ?institution }
}
LIMIT 200
Voer deze query uit en download het resultaat als tabel. Een OpenRefine-project maken (de standaardinstellingen voor de importeur moeten voldoende zijn). De eerste kolom bevat URIs van Wikidata-item. Voorlopig behandelt OpenRefine ze als een andere URL: ze zijn technisch gezien niet met Wikidata verzameld. Om deze cellen een verzamelde status te geven, moet u een verzameling uitvoeren op deze kolom, die aanzienlijk sneller dan normaal moet zijn (omdat er geen zoekopdracht gebeurt - de Qids worden gewoon gevalideerd en teruggestuurd). [1]
De API-query uitvoeren
ORCID biedt een openbare API die zonder registratie kan worden gebruikt om de openbare inhoud van elk ORCID-profiel op te halen. Ze hebben een korte tutorial waarin wordt uitgelegd hoe de API werkt. U hoeft de beschrijving van ORCID van de API niet volledig te begrijpen. Hun gids is vrij ingewikkeld omdat deze geavanceerde functies behandelt die we hier niet nodig hebben. Het enige dat we hoeven te weten, is welke URL we moeten ophalen om de affiliatie-informatie in een gestructureerd formaat te verkrijgen. Om de inhoud van de sectie Employment op te halen, moeten we de volgende URL gebruiken: "https://pub.orcid.org/v2.1/"+value+ "/employments", waarbij +value+ wordt vervangen door de ORCID-identificatie van de persoon. Standaard retourneert dit een antwoord dat is opgemaakt in XML, maar we kunnen vragen om in plaats daarvan JSON op te halen door de HTTP-header toe te voegen Accept: application/json.
We kunnen dit allemaal doen in OpenRefine, met behulp van de bewerking Kolom bewerken → Kolom toevoegen door URL's op te halen in de ORCID-kolom:
Informatie extraheren uit JSON-antwoorden
Zodra de bewerking is voltooid, verkrijgt u de JSON-antwoorden in een nieuwe kolom. Daar moeten we nu informatie uit halen. Elk antwoord bevat mogelijk een lijst met werkgevers, dus de eerste stap is om de subobjecten voor elke werkgever op een aparte regel te extraheren, volgens het recordmodel van OpenRefine. Dit is helaas een ietwat onelegant proces:
- we moeten eerst de lijst met werkgevers extraheren door de JSON-payload te parseren, met behulp van de bewerking Kolom toevoegen op basis van deze kolom (in het menu Kolom bewerken van de kolom employments) met deze expressie: value.parseJson()["employment-summary"].join('###')
- we gebruiken dan de bewerking Splits cellen met meerdere waarden (in het menu Cellen bewerken van de nieuwe kolom), waarbij we hetzelfde scheidingsteken
###specificeren, om elk object op zijn eigen rij te verkrijgen.
Zodra we dit hebben, kunnen we parseJson() opnieuw gebruiken om informatie uit dit object te extraheren. We zullen de volgende velden extraheren (opnieuw met behulp van de bewerking Kolom toevoegen op basis van deze kolom):[2]
- Organisatienaam, met value.parseJson () ["organisation"]["name"]
value.parseJson()["organization"]["name"]
- Organisatie land, met
value.parseJson()["organization"]["address"]["country"]
- Organisatie-identificator, met
value.parseJson()["organization"]["disambiguated-organization"]["disambiguated-organization-identifier"]
- Startdatum van de positie, met
value.parseJson()["start-date"]["year"]["value"]
- Einddatum van de positie, met
value.parseJson()["end-date"]["year"]["value"]
- (Oefening: u kunt ook functietitels extraheren, omdat deze als kwalificaties kunnen worden toegevoegd met position held (P39)).
We kunnen nu de JSON-kolommen verwijderen en de andere opnieuw ordenen. Dit kan eenvoudig worden bereikt met de bewerking Kolommen opnieuw ordenen / verwijderen die beschikbaar is onder Kolommen bewerken in het menu Alle in de hoofdkolom. U zou iets als dit moeten krijgen:
De instellingen afstemmen
Onze resultaten zijn al in overeenstemming, omdat we ze net hebben gekregen uit onze SPARQL-query. De instellingen moeten echter duidelijk worden gemaakt. Wij kunnen ze bij naam afstemmen, maar dat alleen maar zal ons niet ver brengen, omdat deze namen vaak dubbelzinnig zijn. We kunnen het met twee parameters verfijnen: het land en de identificatie.
- ORCID vertegenwoordigt landen met hun ISO 3166-1 alpha-2 code (P297). Omdat deze eigenschap echter niet op het item van de instelling staat, maar op het item van de instelling country (P17), kunnen we niet zomaar ISO 3166-1 alpha-2 code (P297) gebruiken in het afstemmingsdialoogvenster. We hebben twee stapjes nodig om van het artikel naar de landcode te komen. De Wikidata-reconciliatieservice biedt daarvoor een syntaxis (geïnspireerd door SPARQL):
P17/P297.
- De id's die we uit de JSON-payload hebben gehaald, zijn niet altijd dezelfde soort id's. Heel vaak zijn ze Ringgold ID (P3500), maar soms zijn ze GRID ID (P2427) of DOI (P356) (dat eigenlijk wordt opgeslagen als Open Funder Registry funder ID (P3153) in Wikidata). ORCID biedt het type identifier dat ze leveren, dus we kunnen dat gebruiken om ze in verschillende kolommen te scheiden en elke kolom in het afstemmingsdialoogvenster te gebruiken. Deze keer gaan we in plaats daarvan een truc gebruiken: omdat we weten dat de formaten van deze identifiers niet compatibel zijn, zullen we de reconciliatie-interface rechtstreeks vragen om de identifier voor ons te kiezen. Dit kan worden bereikt met behulp van het | teken om een disjunctie te introduceren:
P3500|P2427 komt overeen op de vereniging van beide eigenschappen.[3] We verkrijgen het volgende reconciliatiedialoogvenster:
Het schema aanmaken
Zodra de afstemming is voltooid, kunnen we nu het schema maken. Raadpleeg employer (P108) om meer te weten te komen over de verwachte structuur van dergelijke claims. Het lijkt erop dat het volgende zou kunnen doen:
Nu zijn we nog niet helemaal klaar, want onze tabel heeft een recordstructuur: sommige cellen in de kolom onderzoeker zijn leeg (wanneer een onderzoeker meerdere werkgevers op zijn profiel heeft). Omdat schema-evaluatie rijgewijs werkt, worden de bijbehorende instructies nu overgeslagen (omdat hun onderwerp leeg is). Om dat op te lossen, kunnen we het commando Fill down gebruiken (uit het menu Cellen bewerken van de kolom onderzoeker). Hierdoor worden de waarden over de records verspreid. U moet dit ook doen voor de kolom "orcid", omdat deze waarden worden gebruikt in verwijzingen. Zodra dit is gebeurd, kunt u een voorbeeld van de bewerkingen bekijken in het tabblad Voorbeeld en ze uploaden met de optie Bewerkingen uploaden naar Wikidata van het menu Wikidata in de rechterbovenhoek. U zou bewerkingen moeten krijgen zoals dit of dit. Merk op dat, aangezien deze bewerkingen meerdere verklaringen tegelijk introduceren, hun automatische bewerkingssamenvattingen minder informatief zijn, dus het is belangrijk om een zinvolle bewerkingssamenvatting op te geven om dat te compenseren.
Wat hebben we gedaan?
We hebben een vrij vervelend proces doorlopen voor slechts 200 onderzoekers. Maar het goede nieuws is dat we dit de volgende keer niet hoeven te doen. OpenRefine's ongedaan maken/herstellen tabblad is een beetje geavanceerder dan wat u gewend bent aan van andere software. Niet alleen kunt u uw project terugrollen naar een tussenpositie, maar het stelt u ook in staat om de beschrijving van de bewerkingen als een JSON-object te extraheren en deze bewerkingen opnieuw toe te passen op een nieuw project. Als u de SPARQL-query opnieuw uitvoert (mogelijk met een hogere limiet), kunt u de bewerkingsgeschiedenis toepassen op het nieuwe project. Als u OpenRefine gebruikt om uw bewerkingen direct uit te voeren, telt dat ook als een operatie, dus OpenRefire zal dat ook doen. Gefeliciteerd, u heeft een geavanceerde Wikidata-bot geschreven zonder een enkele regel code!
Hieronder is een voorbeeld van OpenRefine-bewerkingsgeschiedenis die u kunt toepassen op de resultaten van het SPARQL-query om dezelfde resultaten te bereiken:
| JSON-bewerkingsplan |
|---|
[
{
"op": "core/recon",
"description": "Reconcile cells in column researcher to type Q5",
"columnName": "researcher",
"config": {
"mode": "standard-service",
"service": "https://wikidata.reconci.link/en/api",
"identifierSpace": "http://www.wikidata.org/entity/",
"schemaSpace": "http://www.wikidata.org/prop/direct/",
"type": {
"id": "Q5",
"name": "human"
},
"autoMatch": true,
"columnDetails": [],
"limit": 0
},
"engineConfig": {
"mode": "row-based",
"facets": []
}
},
{
"op": "core/column-addition-by-fetching-urls",
"description": "Create column employments at index 2 by fetching URLs based on column orcid using expression grel:\"https://pub.orcid.org/\"+value+\"/employments\"",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"newColumnName": "employments",
"columnInsertIndex": 2,
"baseColumnName": "orcid",
"urlExpression": "grel:\"https://pub.orcid.org/v2.1/\"+value+\"/employments\"",
"onError": "set-to-blank",
"delay": 100,
"cacheResponses": true,
"httpHeadersJson": [
{
"name": "authorization",
"value": ""
},
{
"name": "user-agent",
"value": "OpenRefine 2.8 [TRUNK]"
},
{
"name": "accept",
"value": "application/json"
}
]
},
{
"op": "core/column-addition",
"description": "Create column employment_record at index 3 based on column employments using expression grel:value.parseJson()[\"employment-summary\"].join('###')",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"newColumnName": "employment_record",
"columnInsertIndex": 3,
"baseColumnName": "employments",
"expression": "grel:value.parseJson()[\"employment-summary\"].join('###')",
"onError": "set-to-blank"
},
{
"op": "core/column-removal",
"description": "Remove column employments",
"columnName": "employments"
},
{
"op": "core/multivalued-cell-split",
"description": "Split multi-valued cells in column employment_record",
"columnName": "employment_record",
"keyColumnName": "researcher",
"mode": "separator",
"separator": "###",
"regex": false
},
{
"op": "core/column-addition",
"description": "Create column end_date at index 3 based on column employment_record using expression grel:value.parseJson()[\"end-date\"][\"year\"][\"value\"]+if(value.parseJson()[\"end-date\"][\"month\"] != null, \"-\"+value.parseJson()[\"end-date\"][\"month\"][\"value\"], \"\")",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"newColumnName": "end_date",
"columnInsertIndex": 3,
"baseColumnName": "employment_record",
"expression": "grel:value.parseJson()[\"end-date\"][\"year\"][\"value\"]+if(value.parseJson()[\"end-date\"][\"month\"] != null, \"-\"+value.parseJson()[\"end-date\"][\"month\"][\"value\"], \"\")",
"onError": "set-to-blank"
},
{
"op": "core/column-addition",
"description": "Create column start_date at index 3 based on column employment_record using expression grel:value.parseJson()[\"start-date\"][\"year\"][\"value\"]+if(value.parseJson()[\"start-date\"][\"month\"] != null, \"-\"+value.parseJson()[\"start-date\"][\"month\"][\"value\"], \"\")",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"newColumnName": "start_date",
"columnInsertIndex": 3,
"baseColumnName": "employment_record",
"expression": "grel:value.parseJson()[\"start-date\"][\"year\"][\"value\"]+if(value.parseJson()[\"start-date\"][\"month\"] != null, \"-\"+value.parseJson()[\"start-date\"][\"month\"][\"value\"], \"\")",
"onError": "set-to-blank"
},
{
"op": "core/column-addition",
"description": "Create column organization_id at index 3 based on column employment_record using expression grel:value.parseJson()[\"organization\"][\"disambiguated-organization\"][\"disambiguated-organization-identifier\"]",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"newColumnName": "organization_id",
"columnInsertIndex": 3,
"baseColumnName": "employment_record",
"expression": "grel:value.parseJson()[\"organization\"][\"disambiguated-organization\"][\"disambiguated-organization-identifier\"]",
"onError": "set-to-blank"
},
{
"op": "core/column-addition",
"description": "Create column organization_country at index 3 based on column employment_record using expression grel:value.parseJson()[\"organization\"][\"address\"][\"country\"]",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"newColumnName": "organization_country",
"columnInsertIndex": 3,
"baseColumnName": "employment_record",
"expression": "grel:value.parseJson()[\"organization\"][\"address\"][\"country\"]",
"onError": "set-to-blank"
},
{
"op": "core/column-addition",
"description": "Create column organization_name at index 3 based on column employment_record using expression grel:value.parseJson()[\"organization\"][\"name\"]",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"newColumnName": "organization_name",
"columnInsertIndex": 3,
"baseColumnName": "employment_record",
"expression": "grel:value.parseJson()[\"organization\"][\"name\"]",
"onError": "set-to-blank"
},
{
"op": "core/column-removal",
"description": "Remove column employment_record",
"columnName": "employment_record"
},
{
"op": "core/recon",
"description": "Reconcile cells in column organization_name to type Q43229",
"columnName": "organization_name",
"config": {
"mode": "standard-service",
"service": "https://wikidata.reconci.link/en/api",
"identifierSpace": "http://www.wikidata.org/entity/",
"schemaSpace": "http://www.wikidata.org/prop/direct/",
"type": {
"id": "Q43229",
"name": "organization"
},
"autoMatch": true,
"columnDetails": [
{
"column": "organization_country",
"propertyName": "SPARQL: P17/P297",
"propertyID": "P17/P297"
},
{
"column": "organization_id",
"propertyName": "SPARQL: P3500|P2427",
"propertyID": "P3500|P2427"
}
],
"limit": 0
},
"engineConfig": {
"mode": "row-based",
"facets": []
}
},
{
"op": "core/fill-down",
"description": "Fill down cells in column researcher",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"columnName": "researcher"
},
{
"op": "wikidata/save-wikibase-schema",
"description": "Save Wikibase schema skeleton",
"schema": {
"itemDocuments": [
{
"subject": {
"type": "wbitemvariable",
"columnName": "researcher"
},
"statementGroups": [
{
"property": {
"datatype": "wikibase-item",
"pid": "P108",
"label": "employer",
"type": "wbpropconstant"
},
"statements": [
{
"references": [
{
"snaks": [
{
"prop": {
"datatype": "external-id",
"pid": "P496",
"label": "ORCID iD",
"type": "wbpropconstant"
},
"value": {
"type": "wbstringvariable",
"columnName": "orcid"
}
},
{
"prop": {
"datatype": "time",
"pid": "P813",
"label": "retrieved",
"type": "wbpropconstant"
},
"value": {
"type": "wbdateconstant",
"value": "TODAY"
}
}
]
}
],
"qualifiers": [
{
"prop": {
"datatype": "time",
"pid": "P580",
"label": "start time",
"type": "wbpropconstant"
},
"value": {
"type": "wbdatevariable",
"columnName": "start_date"
}
},
{
"prop": {
"datatype": "time",
"pid": "P582",
"label": "end time",
"type": "wbpropconstant"
},
"value": {
"type": "wbdatevariable",
"columnName": "end_date"
}
}
],
"value": {
"type": "wbitemvariable",
"columnName": "organization_name"
}
}
]
}
],
"nameDescs": []
}
]
}
},
{
"op": "core/fill-down",
"description": "Fill down cells in column orcid",
"engineConfig": {
"mode": "row-based",
"facets": []
},
"columnName": "orcid"
}
]
|
Opmerkingen
- ↑ Dit lijkt misschien een verspilling van tijd: deze afstemming zou triviaal moeten zijn. In de praktijk haalt OpenRefine informatie voor elk item: het etiket, maar ook de interne typen die u kunt gebruiken met de uitdrukking
cell.recon.match.type. - ↑ Het is mogelijk om kortere expressies te verkrijgen door tussenliggende kolommen te maken (zoals
value.parseJson()["organization"]). - ↑ Voor de eenvoud negeren we de DOI (P356) omdat hun formaat niet overeenkomt met het formaat dat op Wikidata wordt gebruikt. Oefening: verwijder het DOI-voorvoegsel uit deze waarden, zodat u ze ook voor reconciliatie kunt gebruiken.