API
Door Theo den Exter (THEX)
Token vernieuwing per 7 Juli 2017
Per 7 juli 2015 heeft GroundSpeak (GS) een nieuw regime t.a.v. tokens ingevoerd.
Dit regime vraagt opnieuw autoriseren voor live-api gebruik iedere 90 dagen.
Wat is een token.
Een token is een stokje. Dit stokje wordt meegegeven om iets te signaleren. Bijvoorbeeld bij een enkelbaans treinrail wordt het unieke token van trein tot trein doorgegeven zodat er slechts 1 trein op de baan kan zijn: namelijk de trein met het token (vaak een vlag). Vergissen en een kop-kop aanrijding is niet mogelijk. Binnen IT wordt een token gebruikt om jou te identificeren. GS gebruikt het token om jouw verbruik per dag bij te houden en bij te houden en om jou te identificeren. Een token is eigenlijk een reeks cijfers en getallen die jouw identiteit representeerd, alsmede je recht om bij GS met een specifieke applicatie toegang te hebben. Dit token, welke verkregen wordt door je applicatie voor de live-api te autoriseren, heeft vanaf 7 juli een beperkte levensduur van 90 dagen gekregen in plaats van een onbeperkte levensduur. Na 90 dagen krijg je een foutmelding en werkt de functionaliteit rond api toegang niet meer. In GSAK versie 8.5 en hoger wordt je 5 dagen van te voren gewaarschuwd. Voorbeeld van een token (een neppert) hier in het formaat wat richting GS gaat: v9i1NkkXMB3kG/P1I /a08y7qZu1=
Waarom heeft GS dit gedaan.
Gerucht gaat dat sommige web-site beheerders de tokens van derden hebben verzameld, en hier gebruik van maken voor eigen diensten door van ieder token er steeds een klein beetje verbruik van af te snoepen. Door de tokens periodiek te verwijderen, zorgt GS ervoor dat het stelen van tokens niet meer zo loont.
Wat is de live-api.
De live-api is de interface (api staat voor "application programming interface") tussen jouw applicatie en GS. Deze api wordt binnen GSAK gebruikt voor alle menu onderdelen beneden "geocaching.com access". De knop om een autorisatie voor die api te vernieuwen vind je in GSAK onder "Get another access token". De live-api betreft niet het ophalen van een PocketQuery vanuit je lokale mail, maar alleen acties die de applicatie uitvoert rechtstreeks op de GS website en niet indirect.
Waar merk ik een verlopen token aan.
De applicatie GSAK, GDAK, GAPP, de 2 GS applicaties voor Iphone en Android, Project-GC en Global maken allen gebruik van de live-api. Bij gebruik van de api zal een foutmelding volgen dat je token niet meer geldig is. Je kunt dan bv geen caches updaten, laatste logs ophalen, etc. Hoe kan ik nu controleren of mijn token goed is: vraag onder "Geocaching.com Access" "Get available download balance". Indien je geen token melding krijgt, functioneert je token nog.
Voor GSAK komt er nog een ding bij: sommige macro's maken ook gebruik van de live-api. Ook deze macro's laten het afweten. Welke macro's dit precies zijn is moeilijk van te voren in te schatten, ik weet niet wat jij gebruikt, zelf geschreven hebt of iemand dit voor je hebt laten doen. Maar ophalen van al je found logs is er 1 van. Of ophalen van de dagelijkse PQ vanuit het GSAK menu.
C:GEO is een uitzondering: deze maakt bewust geen gebruik van de live-api, maar screen-scraped (het automatisch uitlezen en interpreteren van de webpagina's door de software). Screen-scrapen is door GS niet toegestaan, en je merkt dit omdat GS steeds hun webpagina's aanpassen. C:GEO werkt dan niet meer, en moet zich ook aanpassen (wat overigens zeer vlot gebeurd). Dit is een vervelend kat/muis spelletje.
De volgende algemene aanbevelingen gelden.
Installeer de laatste versie GSAK. Dit is aan te bevelen omdat er recente wijzigingen zijn aangebracht in de maximale opdracht/omvang van een live-api aanroep per tijdseenheid. Voorbeeld: ophalen logjes is beperkt tot 60/minuut. Werk niet goed functionerende macro's bij met de laatste versie van die macro. Dit omdat macro's nu in delen info (moeten) opvragen en tussendoor wachten (zie ook het vorig punt), maar vooral ook omdat GS een nieuwe foutmelding geintroduceerd heeft, welke de macro moet herkennen. Heb je een log ophaal macro wat stopt na 60 logjes, dan is die duidelijk aan vervanging toe. Werk eenmalig alle tokens bij.
Macro GlobalcachingCacheStatusUpdate.gsk.
Het populaire macro GlobalcachingCacheStatusUpdate.gsk heeft een aanvullende beperking. Dit macro gebruikt voor het ophalen van favourietstanden het token uit GAPP versies 1.x. De reden is dat GSAK de token van GSAK niet aan het macro doorgeeft, en met het token door Global wordt getest of jij wel premium member bent. Maak je geen gebruik van favo updates, dan geldt het volgende niet voor je.
Het macro slaat dan deze controle over. Het macro dient 2 tokens te vernieuwen: die van GSAK en die van GAPP 1.x. Helaas wordt Gapp 1.x niet meer onderhouden, en het macro zoals op het GSAK Macro forum staat (de 1.9) kan niet met GAPP 2.x omgaan. Ik heb hier een patch voor klaar liggen. Deze staat klaar in het GSAK Gebruikers facebook inclusief instructies.
Het lijkt erop dat GAPP 1.x nog steeds zijn token kan vernieuwen. In GAPP 2.x loopt de token vernieuwing namelijk op een iets andere wijze.
Updaten token/autoriseren.
Onder menu "Geocaching.com access" vind je in GSAK "Get another access token". Een IE pop-up scherm verschijnt, en je mag je aanmelden op GS (als dat niet standaard al gebeurd is).
Noot: Internet Explorer 6/7/8 wordt niet meer door GS ondersteund. Concreet (is van de week gebleken) betekent dit dat je onder Windows XP geen nieuw token meer kunt aanvragen ! Zie ook de tip beneden aan in dit document.
Token vernieuwing wil niet lukken.
Indien onder GSAK een token zich niet laat vernieuwen, kun je dit aanpakken op de volgende manier: GSAK beëindigen.
Internet Explorer opstarten (geen andere browser kiezen, GSAK maakt onder de motorkap gebruik van IE).
Inloggen op GS (indien nodig). Autorisatie verwijderen.
Uitloggen op GS.
Cookies van GS verwijderen in je browser (dit is de belangrijkste stap). GSAK opstarten en opnieuw proberen.
Verwijderen cookie:
- Open Internet Explorer (it must be Internet Explorer - not another browser).
- Go to Tools>Internet Options, General tab.
- Click the Settings button
- Click the View Files button
- Type "Geocaching" (without the quotes) into the search box in the upper right corner of that window.
- Delete the file "cookie:?????@geocaching.com/" where ????? is probably your Windows user name.
- In GSAK, go to Geocaching.com Access>Get another access token. Log in to Geocaching.com and authorize GSAK.
- Try using the Geocaching.com Access menu items again.
TIPS
Tip 1
In GSAK 8.5.x zit onder tools => open ConfigOther.txt een item [GroundSpeak Api]. Daar zit een veldje TokenExpireDays=5 onder met een # ervoor. De 5 dagen kun je aanpassen. Deze instelling zorgt ervoor dat 5 dagen voor je token afloopt, je een waarschuwing krijgt. De GSAK versie 8.4.x en eerdere versies hebben deze optie niet.
Tip 2
De live-api interface tussen GS en GSAK zijn in gedrag aan te passen. Voor situaties waarin response van GS erg langzaam is, zoals afgelopen weken gedurende de zomer avonddrukte, kun je het volgende proberen:
In GSAK 8.5.x zit onder tools => open ConfigOther.txt een item [GroundSpeak Api]. Daar zitten de volgende 4 veldjes in (met andere waarden): #TimeOutSeconds=120
#AutomaticRetries=40
#RetryDelaySeconds=60
#EventTimeOutSeconds=240
Om GSAK wat meer "agile" te maken, kun je de standaard waarden aanpassen zoals hierboven gesuggereerd wordt. De waarden zijn meteen van kracht als je het bestand opslaat.
Bovenstaande betekent: tussen retries zit 60 seconden, maximaal 40 retries. Een retry gaat in nadat 120 seconden geen response ontvangen is. Het gevolg van deze instellingen is dat een traag lopende GS opgevangen wordt door steeds opnieuw te proberen. Maar ook dat een opdracht soms start met een ongepaste foutmelding (als gevolg van de vorige actie) of pas na 60 seconden en een hoop extra meldingen. Een hoop meldingen verschijnen in een box, zeker als de verbose mode aanstaat (vinkje in verbose), maar GSAK blijft proberen de aanvraag af te ronden (enkele minuten). De meldingen zijn niet erg.
Tip 3
Er is een probleem geconstateerd in de actuele versie 8.5.1.42 van GSAK. Als GSAK gedurende een onafgemaakte api opdracht tussendoor om een nieuw token vraagt, wordt het verkregen token niet correct in GSAK verwerkt. Je moet het actuele proces eerst compleet beëindigen, en dan een nieuw token aanvragen middels "Get another access token". Clyde is aan een oplossing aan het werken.
Messages from GSAK Forum.
Noot: een betere optie staat beneden aan in dit document.
Is there any other way to get the token that does not require a new computer and new version of Windows?
Install GSAK on a more recent computer (doesn't have to be "your" computer), then fetch your access token. Then take the option "File=>Backup" and just back up the settings. Restore this backup on your old computer and it should then update your old computer with the new access token. GC Token problem - maybe XP problem.
Here is what I did to get around it for now (hopefully GSAK finds a real fix).
I read what Clyde said about using another computer to get a token and then use that. I tried what he suggested about just getting settings, but I had some mixed results so I did a full blown job.
1. Did a complete GSAK backup using GSAK backup function on my XP Computer to a jumpdrive (could use an external HD or even the cloud (Dropbox))
2. Using GSAK restore function I restored everything to a WIN 7 laptop which had GSAK on it.
a. This did cause me some confusion because the restore crashed when it tried to restore I believe GSAK.EXE (not sure how to get around it, but GSAK still worked)
3. Then I requested a new token on the WIN7 computer, which worked fine
4. Using the GSAK backup function I just backed up the settings on the WIN7 computer to the jumpdrive (cleared databases checks and checked "Save GSAK Settings")
5. Than on XP Computer I did a GSAK Restore from the jumpdrive, just the settings.
a. Again I had trouble with GSAK.EXE, but It did restore
6. The GEOCACHING.COM functions now worked.
a. Do not ask for another token on the XP computer
I’m sure there is a better or more streamlined way to do what is needed, that is getting the GC token from the WIN7 computer to the XP computer. I suspect that maybe only one or two files are where everything is stored, but I wasn't sure so I did everything for now.
As far as giving up on XP, would love to, but it is much easier said than done!
Commentaar van het GSAK Forum team.
Based on all of the posts on this topic (there have been many since Geocaching.com started expiring tokens on 7 July), here's a summary of what appears to be happening and the actions to take in each case:
1) If you get the GSAK semi-automatic token retrieval message, GSAK will retrieve a new token, but it will not be applied immediately. You have to abort whatever process you are in and start over for the new token to take effect.
2) If you receive the expired token warning from Groundspeak (independent of GSAK's prompt to retrieve a new token), or if the semi-automatic retrieval does not appear to work, go to Geocaching.com Access>Get Another Access token.
3) If you are unable to log in and authorize GSAK:
a. Ensure that you are using at least Windows XP Service Pack 3 and Internet Explorer 8, the newest version of IE supported under Windows XP (if you are using Windows 7 or newer, it's best to update IE to version 11).
b. If you are using at least Windows XP SP3 and IE 8 and still cannot log in to Geocaching.com to authorize GSAK, follow these steps to delete the geocaching.com cookie on your computer and get a new access token:
i) Open Internet Explorer (it must be Internet Explorer - not another browser).
ii) Go to Tools>Internet Options, General tab.
iii) Click the Settings button
iv) Click the View Files button
v) Type "Geocaching" (without the quotes) into the search box in the upper right corner of that window.
vi) Delete the file "cookie:?????@geocaching.com/" where ????? is probably your Windows user name.
vii) In GSAK, go to Geocaching.com Access>Get another access token. Log in to Geocaching.com and authorize GSAK.
viii) Try using the Geocaching.com Access menu items again.
Voorkomen van IE 6/7/8, mogelijkheid gebruik GSAK onder Windows XP
In build 45 zit een "methode 2" optie. M.b.v. deze methode is het met je default browser (firefox bv) mogelijk het token te verversen buiten GSAK om (dus buiten GSAK's intern gebruik van IE om). Na aanmelden op GS komt er een boxje naar welk programma de token gezonden moet worden. Hier moet uiteraard GSAK in worden vermeldt. Zie posting: http://gsak.net/board /index.php?s=353005541ca1888de84b4a6fceea0cda&showtopic=29969&st=80