Erstellen Sie Ihre eigene Seifen-API

Ich bin mir sicher, dass Sie alle bemerkt haben, dass dieses Magazin vor einigen Ausgaben umfassend überarbeitet wurde, und wir haben den neuen Slogan 'Entwickeln / Entdecken / Entwerfen' übernommen. Nun, ich bin ein Mann mit so wenig Sinn für Aussehen, dass ich mich im Dunkeln anziehe, also kann ich dir nichts über Design beibringen. Ich hoffe, Sie haben sich in den letzten beiden Ausgaben mir angeschlossen, um herauszufinden, wie Sie die hervorragenden APIs von Google, Flickr und Delicious nutzen können, um zusätzlichen Inhalt für Ihre Website zu erhalten.

In dieser Ausgabe werden wir uns mein Lieblingsmitglied der .net-Dreifaltigkeit ansehen: 'Entwickeln'. Bei der Arbeit mit Google mussten wir Soap und WSDL verwenden, zwei der einfachsten Methoden, um eine strenge API zu definieren, auf der andere aufbauen können. Wir haben bereits die ausgezeichnete SoapClient-Klasse verwendet, aber es gibt eine ebenso hervorragende SoapServer-Klasse, die auch mit WSDL funktioniert, und wir können sie kombinieren, um unsere Inhalte dank PHP mit der Welt zu teilen. Natürlich wird unser Code jedem, der ihn anfordert, Inhalte bereitstellen, unabhängig davon, ob er PHP verwendet oder nicht, aber unser Server wird mit PHP geschrieben.

Der Vorteil der Verwendung von WSDL besteht darin, dass wir unsere API auf klare, plattformübergreifende Weise unter Verwendung eines offenen XML-Standards definieren, anstatt zu versuchen, einige tausend Zeilen PHP zu schreiben, und dann die gesamte Dokumentation dazu schreiben müssen. WSDL bildet die Grundlage für unseren Code, ist jedoch auch selbstdokumentierend. Dies ist perfekt für alle, die keine Freude daran haben, Dokumentation zu schreiben (das sind wir alle). Die Tatsache, dass unsere WSDL die Basis für unseren Client- und Servercode darstellt, ist ein zusätzlicher Bonus, der bedeutet, dass Sie nur eine Datei ändern müssen, um Ihre API auf dem neuesten Stand zu halten.



WSDL ausarbeiten

Der allererste Schritt beim Erstellen einer API besteht darin, zu entscheiden, was Sie tatsächlich erreichen möchten. Dies erfolgt normalerweise über Anwendungsfalldiagramme, mit denen eine Liste der erforderlichen Ein- und Ausgänge für einen Prozess erstellt werden soll. Ich habe auf diesen Seiten nicht genügend Platz, um eine Software-Ingenieurschule zu eröffnen, daher werde ich die Anforderungen recht einfach halten: Ich werde Rätsel lösen. Zu diesem Zweck definiert die API eine Funktion getPuzzle (), die eine Anforderung an den Server sendet, der dann zufällig ein Puzzle auswählt und zurücksendet. Um die Sache etwas schwieriger zu machen, lassen Sie die Leute angeben, welchen Schwierigkeitsgrad sie möchten, wobei Stufe 1 die einfachste und Stufe 3 die schwierigste ist.

Nun ein Wort der Warnung: Wenn Sie mit WSDL arbeiten, ist es immer am schwierigsten, den ersten Arbeitscode zu erstellen. Ihr grundlegendes WSDL-Skript enthält nur knapp 40 XML-Zeilen, und es ist nicht so einfach zu verstehen, wie Sie vielleicht denken. Das eigentliche PHP, um die ganze Angelegenheit voranzutreiben, ist im Vergleich ein Kinderspiel, aber Sie müssen zuerst die WSDL schreiben.

Tragetasche für MacBook Pro 13

Um die Lesbarkeit zu verbessern, empfiehlt es sich, die WSDL in zwei Teile zu unterteilen. Speichern Sie die gesamte Datei als 'dotnet1.wsdl' und stellen Sie sicher, dass sie sich in Ihrem öffentlichen HTML-Verzeichnis befindet. Hier ist der erste Teil:

Die ersten beiden Zeilen sind Standard-XML-Tarife. Sie werden jedoch feststellen, dass Sie eine Reihe von XML-Namespaces einbeziehen müssen, da verschiedene Technologien verwendet werden. In den nächsten beiden Abschnitten werden die 'Nachrichten' und 'Operationen' definiert, die wir ausführen möchten. Jede Nachricht wird entweder an den Server gesendet oder zurück empfangen. Hier legen Sie genau fest, was die Nachrichten enthalten sollen. Für Ihre Grundbedürfnisse habe ich gesagt, dass die getPuzzle-Nachricht eine Zahl enthalten muss ('int' steht für 'integer', was 'ganze Zahl' bedeutet), die die schwierige Bewertung darstellt, und dass die Rätselantwort in der Form vorliegen sollte einer Zeichenfolge.

Unter den Nachrichten befindet sich das Element portType, aber machen Sie sich darüber noch keine Sorgen. Achten Sie vorerst nur auf den Inhalt, der besagt, dass es eine Operation (eine Funktion in der PHP-Terminologie) namens getPuzzle () gibt, die über die Nachricht getPuzzle () aufgerufen wird und eine Nachricht getPuzzleResponse () zurückgibt. Es sind Operationen, die Nachrichten zu Funktionen zusammenfügen, weshalb der Name der Operation, getPuzzle, der PHP-Funktion getPuzzle () zugeordnet wird. Hier ist die andere Hälfte der WSDL-Datei:

Das gesamte Element ist erforderlich, kann jedoch weitgehend ignoriert werden. Es heißt, dass die getPuzzle-Operation Soap sowohl für die Eingabe als auch für die Ausgabe verwendet. Im echten XML-Stil sind jedoch mehr als 10 Codezeilen erforderlich, um dies zu sagen. Wenn Sie in Zukunft Ihre eigenen Vorgänge hinzufügen möchten, kopieren Sie diesen Großhandel einfach und fügen Sie ihn ein. Sie müssen nichts anderes als den Namen des verwendeten Vorgangs ändern.

Das letzte Element ist sehr wichtig, da es definiert, wo sich der Dienst im Internet befindet. Das zuvor erwähnte portType-Element verweist darauf, bevor die verfügbaren Operationen beschrieben werden. In der Praxis bedeutet dies, dass Sie verschiedene Vorgänge haben können, die auf verschiedene Skripte verweisen, wenn Sie möchten.

Sie haben jetzt Ihre Parameter (oder 'Nachrichten' in Soap-speak), Ihre Funktion ('Operation'), Ihr Protokoll ('Bindung') und Ihre URL ('Dienst') definiert, was bedeutet, dass Sie alles haben, was Sie brauchen um einen vollständigen Funktionsaufruf durchzuführen. Dies bedeutet, dass Sie XML vorerst hinter sich lassen und zu PHP wechseln können.

Client und Server

Nach so viel XML wird dieser Code Sie wahrscheinlich zum Lachen bringen:

getPuzzle('1');?>

Es sind nur zwei Zeilen PHP erforderlich, um die API zu laden, den Funktionsaufruf durchzuführen und die Ergebnisse zu drucken. Speichern Sie dies als '1.php' im selben Verzeichnis wie Ihre WSDL-Datei. Dieser Code fordert vom Server ein einfaches Rätsel an, daher müssen Sie die letzte Komponente der API programmieren: den Server. Dies muss die Seifenanforderung akzeptieren, die Funktion getPuzzle () ausführen und dann das Puzzle für den Client ausgeben. PHP erledigt die meiste harte Arbeit für Sie, was den Code bemerkenswert kurz macht:

addFunction('getPuzzle');$server->handle();?>

Der Hauptteil dieses Skripts ist die Funktion getPuzzle (), die einen Parameter zum Speichern der angeforderten Schwierigkeit verwendet. Diese Funktion speichert Ihre Rätsel im Array $ puzzles. Wenn Sie dies jedoch ernsthaft implementieren möchten, sollten Sie zu einer SQL-Datenbank mit einer ähnlichen Abfrage wechseln:

SELECT Frage aus Rätseln WHERE Schwierigkeitsgrad = $ Schwierigkeit ORDER BY rand ()
LIMIT 1;

Die Funktion gibt einen Wert zurück, indem sie eine Frage zufällig aus dem $ puzzles-Array mit dem richtigen Schwierigkeitsgrad herausholt. Natürlich hat jeder Schwierigkeitsgrad nur eine Frage, daher wird immer dieselbe Frage zurückgegeben! Die drei Zeilen am Ende des Skripts enthalten die Soap-Magie, die unsere PHP-Funktion mit dem Aufruf von Soap getPuzzle () verbindet. Sie müssen addFunction () für jede Soap / PHP-Bridge aufrufen, die Sie registrieren möchten. Wenn Sie fertig sind, müssen Sie lediglich die handle () -Methode aufrufen, damit PHP die Soap-Eingabe analysiert, an die entsprechenden Funktionen weiterleitet und den Wert an den Client zurücksendet.

Ich weiß, dass Sie wahrscheinlich darauf aus sind, den Code auszuführen, aber Sie müssen zuerst den WSDL-Cache von PHP deaktivieren. Sie haben bereits gesehen, dass die WSDL, die für einen einzelnen Funktionsaufruf erforderlich ist, sehr lang ist. Um zu vermeiden, dass sie jedes Mal analysiert und überprüft werden muss, wenn ein Client vorbeikommt, speichert PHP die WSDL in ihrem analysierten Zustand zwischen. Während Sie sich noch in der Entwicklungsphase befinden, verursacht dies Probleme. Änderungen an der WSDL-Datei werden von PHP nicht erkannt, da weiterhin die zwischengespeicherte Version verwendet wird. Die Lösung besteht darin, das PHP-Caching-System vorübergehend zu deaktivieren. Dies kann durch Ändern der Datei 'php.ini' erreicht werden. Suchen Sie nach der Zeile 'soap.wsdl_cache_enabled' und ändern Sie sie in '0'.

Wenn diese Änderung implementiert ist (starten Sie Apache neu, wenn Sie PHP als Modul ausführen), laden Sie Ihr Skript '1.php'. Sie sollten 'Was ist das beste Webmagazin der Welt?' Sehen, das zeigt, dass unser Client eine Nachricht vom Server erhalten hat.

Arbeiten

Bevor wir fertig sind, möchte ich noch drei letzte Punkte ansprechen, damit Sie stets den Überblick über Ihre WSDL behalten. Stellen Sie zunächst sicher, dass Ihre API stabil ist. Wenn sich die Leute daran gewöhnt haben, Ihre getPuzzle () -Methode aufzurufen, ändern Sie sie nicht. Fügen Sie keine neuen Parameter hinzu, ändern Sie nicht den Datentyp vorhandener Parameter und ändern Sie auf keinen Fall drastisch, was die Funktion tatsächlich tut. Das bedeutet nicht, dass Sie Ihren PHP-Code nicht umschreiben können, damit getPuzzle () das Gleiche auf intelligentere Weise tut. Wenn Sie jedoch die API wirklich ändern müssen (dh einen Parameter hinzufügen oder was auch immer), lassen Sie den alten in Ruhe und erstelle ein neues mit dem Namen getPuzzle2 (). Vergessen Sie zweitens nicht, Personen zu benachrichtigen, wenn sich Ihre WSDL-Datei ändert, damit sie die neueste Version herunterladen können, um die neuesten Funktionen nutzen zu können. Obwohl PHP nicht zwischen Ints und Strings unterscheidet, wählen andere Sprachen diese mit Bedacht aus.

Hoffentlich haben Sie gesehen, dass die Verwendung von Soap - zumindest wenn Sie den anfänglichen Schmerz beim Schreiben von WSDL überwunden haben - einfach ist. PHP erspart Ihnen so viel Aufwand bei der Datenübertragung, dass Sie sich darauf konzentrieren können, dass Ihre Funktionen auf Client- und Serverseite korrekt sind. Wenn Sie mit WSDL weiter vorankommen, werden Sie lernen, die Ausführlichkeit zu schätzen, da PHP einige grundlegende Typprüfungen Ihrer Daten durchführen kann, um sicherzustellen, dass Sie den richtigen Inhalt über Soap senden.