SOAP und AppleScript

Verfasst von Kai Surendorf am 2. Juni 2006 - 11:05

Ebenso wie XML-RPC basiert auch das Simple Object Access Protocoll auf der Übermittlung von XML-Dateien zwischen dem Rechner des Anwenders und dem Server. Bei der Entwicklung des SOAP-Standards wurden etwas andere Kriterien zu Grunde gelegt als bei XML-RPC. Generell bietet die Arbeit mit SOAP deutlich mehr Funktionen als XML-RPC und das Protokoll eignet sich auch für umfangreichere Aufgabengebiete. Dies ist auch der Grund, warum sowohl Amazon als auch Google für ihre Webservices SOAP verwenden. AppleScript kann einen Webservice über SOAP ansprechen. Die Programmierschnittstelle von Google wird in diesem Artikel als Beispiel verwendet. Einerseits lassen sich hier recht schnell brauchbare und einleuchtende Ergebnisse erreichen und andererseits wurde die Schnittstelle von Google sehr umfassend und präzise dokumentiert. Die benötigten Funktionen und Parameter lassen sich in der Dokumentation recht schnell auffinden.

Registrierung bei Google

Google verlangt eine Registrierung, um Anfragen an die Schnittstelle senden zu dürfen. Diese kann unter http://www.google.com/apis/ kostenlos beantragt werden. Jedem registrierten Entwickler teilt Google einen Lizenzschlüssel zu, der bei jeder Abfrage übergeben werden muss. (In den Beispielen in diesem Artikel wird der Lizenzschlüssel mit 123456 angegeben.)

Web Service Description Language - WSDL

Nach erfolgter Registrierung wird das developer's kit benötigt, das bei Google ebenfalls kostenfrei herunter geladen werden kann. In diesem Paket findet sich die Dokumentation der Programmierschnittstelle (APIs_Reference.html) sowie eine ganze Reihe von Beispielen für verschiedene Programmiersprachen wie Java, C# und Visual Basic. Die Beispiele sind für die Arbeit mit AppleScript nicht weiter von Relevanz. Wichtig ist jedoch die in dem Paket enthaltene Datei GoogleSearch.wsdl. Die Dateiendung steht hier für Web Service Description Language. Die Datei enthält die genauen Spezifikationen, welche Methoden über die Schnittstelle von Google angesprochen werden können und welche Parameter anzugeben sind. Im weiteren Sinn handelt es sich hier um ein Pendant zur Bibliothek des Skripteditor.

Anders als C# und Java ist AppleScript nicht in der Lage, eine WSDL-Datei direkt zu interpretieren. Die in der Datei enthaltenen Anweisungen müssen zuvor mit einem speziellen Programm in eine für AppleScript verständliche Form übersetzt werden. Das benötigte Programm WSMakeStubs wird mit Xcode installiert und befindet sich im Ordner /Developer/Tools. Es kann am Terminal ausgeführt werden und verwandelt die in einer WSDL-Datei enthaltenen Vorgaben in ein AppleScript, das für eigene Skripten verwendet werden kann. Zur Konvertierung der WSDL-Datei ist am Terminal zuerst in das Verzeichnis zu wechseln, das die Datei GoogleSearch.wsdl enthält. Mit dem Aufruf /Developer/Tools/WSMakeStubs -x applescript -file GoogleSearch.wsdl wird die Datei interpretiert und in Form eines AppleScripts in der Datei WSStub.as gespeichert.

Die WSDL-Datei wurde in ein AppleScript übersetzt.

Die Datei WSStub.as enthält ein AppleScript script GoogleSearchService, dass die über die Google-Schnittstelle bereitgestellten Methoden in den drei Funktionen doSpellingSuggestion, doGoogleSearch und doGetCachedPage realisiert. Es gibt nun zwei Möglichkeiten, mit diesem Skript zu arbeiten. Zuerst ist es möglich, die Anweisungen direkt in dieser Datei auszuführen. Dazu kann das Skript mit einem tell-Block in der Form tell GoogleSearchService angesprochen werden. Es ist auch möglich, das Skript irgendwo zu speichern und mit load script (mehr) einzubinden. Für die nachfolgenden Beispiele müssen die Zeilen script GoogleSearchService und end script aus der Datei gelöscht werden. Die Datei wird im persönlichen Verzeichnis des Benutzers kai gespeichert.

Drei Funktionen

Google stellt über seine Webservices drei Funktionen zur Verfügung. Mit doSpellingSuggestion wird bei einem (vermeintlichen) Tippfehler eine alternative Schreibweise vorgeschlagen. Diese Funktion ist über den Webservice nur für Englisch verfügbar. Eine Suche zu einem Begriff wird über die Funktion doGoogleSearch ausgeführt, die über eine Reihe von Parametern unter anderem zur Auswahl des Sprachgebiets gesteuert werden kann. Schließlich kann, sofern vorhanden, über doGetCachedPage eine Seite aus de Cache von Google abgerufen werden.

Suche über Google ausführen

Vor dem eigentlichen Skript steht auch hier wieder die Lektüre der Dokumentation, die in der Datei APIs_Reference.html enthalten ist. Die Funktion doGoogleSearch nimmt insgesamt zehn Parameter entgegen. Aus diesen Parametern wird dann gemäß der WSDL-Datei eine Abfrage formuliert. Diese wird, wie auch bei der Arbeit mit XML-RPC, mit einem tell-Block an den URL des Webservice (http://api.google.com/search/beta2) geschickt. Der eigentliche Aufruf des Webservice wird hier jedoch nicht mit call xmlrpc sondern mit call soap realisiert.

on doGoogleSearch(in_key, in_q, in_start, in_maxResults, in_filter, in_restrict, in_safeSearch, in_lr, in_ie, in_oe)
    tell application "http://api.google.com/search/beta2"
        set mn to "doGoogleSearch"
        set sa to "urn:GoogleSearchAction"
        set mns to "urn:GoogleSearch"
        set params to {}
        set paramOrder to {}
        set params to params & {|key|:(in_key as string)}
        set paramOrder to paramOrder & "key"
        set params to params & {q:(in_q as string)}
        set paramOrder to paramOrder & "q"
        set params to params & {start:(in_start as integer)}
        set paramOrder to paramOrder & "start"
        set params to params & {|maxResults|:(in_maxResults as integer)}
        set paramOrder to paramOrder & "maxResults"
        set params to params & {filter:(in_filter as boolean)}
        set paramOrder to paramOrder & "filter"
        set params to params & {restrict:(in_restrict as string)}
        set paramOrder to paramOrder & "restrict"
        set params to params & {|safeSearch|:(in_safeSearch as boolean)}
        set paramOrder to paramOrder & "safeSearch"
        set params to params & {lr:(in_lr as string)}
        set paramOrder to paramOrder & "lr"
        set params to params & {ie:(in_ie as string)}
        set paramOrder to paramOrder & "ie"
        set params to params & {oe:(in_oe as string)}
        set paramOrder to paramOrder & "oe"
        set params to params & {record order:paramOrder}
        return call soap {method name:mn, parameters:params, SOAPAction:sa, method namespace uri:mns}
    end tell
end doGoogleSearch

Die zu übergebenden Parameter haben laut der Dokumentation von Google folgende Bedeutungen:

in_key: Der von Google zugeteilte Lizenzschlüssel.
in_q: Der Begriff, nach dem gesucht werden soll.
in_start: Die erste auszugebende Fundstelle. Mit 1 beginnen die Ergebnisse mit der ersten, mit 20 mit der zwanzigsten Fundstelle.
in_maxResults: Die Anzahl der auszugebenden Fundstellen. Derzeit ist diese auf maximal 10 begrenzt.
in_filter: Der Filter gruppiert sehr ähnliche Treffer und kann bei Bedarf ausgeschaltet werden.
in_restrict: Ermöglicht die Einschränkung auf einen bestimmten Bestand von Google. Sowohl in Bezug auf das Land als auch das Thema. Die Angabe mac würde einer Suche über http://www.google.com/mac entsprechen.
in_safeSearch: Die Kindersicherung.
in_lr: Hiermit wird die Sprache vorgegeben, in der gesucht werden soll.
in_ie: Die Textcodierung, die für die Suchabfrage verwendet werden soll. In den Standardeinstellungen wird UTF-8 verwendet, was mit AppleScript keine Probleme bereitet.
in_oe: Die Textcodierung, die für die Suchergebnisse verwendet werden soll. Auch hier liefert die Standardeinstellung UTF-8 gute Ergebnisse.

Wenn die mittels WSMakeStub erstellte Datei unter /Users/kai/google.scpt gespeichert und in dieser vorher die Zeilen script GoogleSearchService und end script gelöscht wurden, dann kann eine Suche bei Google mit folgendem Skript ausgeführt werden:

set Google to load script "MrsBrain:Users:kai:google.scpt" as alias
tell Google
set Ergebnisse to doGoogleSearch("123456", "Apple", 1, 10, "", "mac", "", "lang_de", "", "") as list
end tell

Mit load script wird zuerst das extern gespeicherte Skript eingebunden und mit dem Namen Google versehen. Mit der set-Anweisung wird die Suche ausgeführt und die Ergebnisse stehen dann in Form einer Liste in der Variable Ergebnisse zur Verfügung. Die Liste enthält neben den Suchergebnissen an zehnter Stelle noch einige weitere Angaben wie etwa die Dauer der Suche in Sekunden. Um auf die Suchergebnisse zugreifen zu können, kann das zehnte Element mit set Fundstellen to item 10 in Ergebnisse ausgelesen werden. Jedes Suchergebnis in der Liste ist ein Datensatz. Dieser enthält neben der Überschrift (title) die Adresse (|url|) und eine Beschreibung (snippet).

Die Treffer werden in einer Liste ausgegeben.

set Google to load script "MrsBrain:Users:kai:google.scpt" as alias
tell Google
    set Ergebnisse to doGoogleSearch("123456", "Apple", 1, 10, "", "mac", "", "lang_de", "", "") as list
    set Fundstellen to item 10 in Ergebnisse
    repeat with Fundstelle in Fundstellen
        set Adresse to |url| in Fundstelle
        open location Adresse
    end repeat
end tell

In dem obigen Beispiel wird wiederum eine Suche nach »Apple« im deutschen Sprachraum im Datenbestand mac ausgeführt. Die Liste wird dann auf die eigentlichen Treffer reduziert. In der repeat-Schleife wird die Liste mit den Treffern durchlaufen, die Eigenschaft |url| eines jeden Eintrags ausgelesen und anschließend mit open location im Standard-Browser geöffnet. Wenn das Skript seine Arbeit verrichtet hat, hat der Browser alle zehn Treffer automatisch geladen.

Weitere Möglichkeiten

Neben der Einsparung von Mausklicks, die mit dem automatischen Aufruf aller zehn Fundstellen einher geht, lässt sich die Schnittstelle von Google natürlich für eine Vielzahl von Programmen und Aufgaben nutzen. Möglich wäre zum Beispiel bei einem Web-Projekt, bei ausgewählten Seiten eine Suche nach dem behandelten Thema auszuführen und die Fundstellen im Kontext anzubieten. Auch der »Google des Tages« des Schockwellenreiters beruht auf einer automatischen Abfrage bei Google.