Embedded Files
Einleitung
Einleitung
Mit der URL-Queue API-Schnittstelle ist es möglich, einzelne URL's zur Erstellung von Karten in einer Datei zusammenzufassen und mit einem Aufruf zu übermitteln.
Die Daten werden dann intern parallel berechnet und nach Erstellung zusammengefasst zurückgeliefert.
Voraussetzungen
Voraussetzungen
Um die URL-Queue Schnittstelle zu verwenden, gibt es 2 Voraussetzungen:
1. Einen Benutzernamen und ein Passwort zum Verwenden des Dienstes.
Die Zugangsdaten erhalten sie von Ihrem Partner oder direkt von locr.
Um sich mit dem Server zu verbinden, ist eine Authentifizierung nötig, die hier beschreiben wird:
2. Die Vorgabe des zu verwendenden Servers, z.B.: http://maps1.locr.com
Aufbau einer Datei für die URL-Queue (XML-Struktur)
Aufbau einer Datei für die URL-Queue (XML-Struktur)
Die hochzuladene XML-Datei muss mit folgender Struktur erstellt werden:
<?xml version="1.0" encoding="utf-8"?>
<batch>
<requests>
<request>
<url>/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=12.3456&latitude_max=23.4567&longitude_min=34.5678&longitude_max=45.6789</url>
<filename>1</filename>
</request>
<request>
<url>/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=12.4567&latitude_max=23.5678&longitude_min=34.6789&longitude_max=45.7890</url>
<filename>2</filename>
</request>
<request>
<url>/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=13.3456&latitude_max=24.4567&longitude_min=35.5678&longitude_max=46.6789</url>
<filename>3</filename>
</request>
</requests>
</batch>
Eine XML-Datei darf nicht mehr als 10.000 Aufrufe beinhalten! Zu viel enthaltene Aufrufe werden ignoriert!
Es muss für jede zu erstellenden Karte die korrekte URL angegeben werden!
Außerdem kann der gewünschte Rückgabe-Dateiname angegeben werden, bei keiner Angabe wird ein Default HASH-Wert verwendet!
Hochladen der XML-Datei für die URL-Queue (init)
Hochladen der XML-Datei für die URL-Queue (init)
Zum Anlegen einer neuen URL-Queue wird zuerst die zu verarbeitende Datei hochgeladen.
Dazu schickt man ein POST-Request mit dem enctype "multipart/form-data" an folgende Adresse:
https://maps1.locr.com/api/url_queue.php?action=init
Um eine Kartenerstellung von bis zu 10000 Karten in Auftrag zu geben, müssen folgende Parameter angegeben werden:
file= "filename.xml" oder "filename.zip"
HTTP-Formular Beispiel:
<form action="" method="post" target="Datenimport">
<input name="action" type="text" value="init"/>
<input name="file" type="file"/>
</form>
Optionale Parameter:
HTTP-Formular Beispiel:
<form action="https://maps1.locr.com/api/url_queue.php" method="post" target="Datenimport">
<input name="action" type="text" value="init"/>
<input name="file" type="file"/>
<input name="email_notifcation" type="text" value="test@email.com"/>
<input name="alternative_url" value="http://maps1.locr.com/?print=1&config=26&width_cm=29.7&height_cm=21&....."/>
<input name="ftp_host" value="ftp.host.com"/>
<input name="ftp_username" value="username"/>
<input name="ftp_password" value="password"/>
</form>
email_notification :
Es wird eine Benachrichtigungmail nach Abschluss des Auftrags versendet
alternative_url:
Angabe einer alternativen Karten-URL, falls die Karte aus irgendeinem Grund nicht erstellt werden konnte!
FTP-Trigger file
Es wird eine XML-Datei mit den Status-Informationen nach Abschluss des Auftrags auf den angegebenen FTP-Server hochgeladen.
ftp_host:
ftp_username:
ftp_password:
Angabe von Benutzername und Passwort, der beim FTP-Server ggf. mit angegeben werden muss.
Beispiel:
https://maps1.locr.com/api/url_queue.php?action=init&urlfile.xml
https://maps1.locr.com/api/url_queue.php?action=init&urlfile.zip
Rückgabe bei erfolgreichem Import
Rückgabe bei erfolgreichem Import
Wenn der Import funktioniert hat, so bekommt man eine XML mit der Anzahl der Datensätze und eine Id zurück, mit der weitergearbeitet wird.
Beispielrückgabe beim Import:
<?xml version="1.0" encoding="utf-8"?>
<batch id="1" status="initialized">
<requests status_not_processed="10">
</batch>
Rückgabe bei fehlerhaftem Import
Rückgabe bei fehlerhaftem Import
Bei einem Fehler kommt eine XML mit folgender Struktur zurück:
Beispiel-Abfrage: https://maps1.locr.com/api/url_queue.php?action=stat&id=1
<?xml version="1.0" encoding="utf-8"?>
<error type="invalid_parameter_value">
<details>invalid parameter value "stat" for "action"</details>
</error>
Statusabfrage einer URL-Queue (status)
Statusabfrage einer URL-Queue (status)
Wichtig in der Rückgabe ist hierbei die Id, die man für weitere Anfragen auf diesen URL-queue benötigt.
Wenn man zum Beispiel, den Status abfragen will, muss man folgende Abfrage machen:
https://maps1.locr.com/api/url_queue.php?action=status&id=1
Wenn der Job erfolgreich abgeschlossen wurde, wird folgendes Ergebnis zurück geliefert:
<?xml version="1.0" encoding="utf-8"?>
<batch id="1" status="completed">
<archive href="https://maps1.locr.com/api/url_queue.php?action=download_archive&id=1" size="1234567"/>
<requests count="3">
<request status="ok">
<url>https://maps1.locr.com/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=12.3456&latitude_max=23.4567&longitude_min=34.5678&longitude_max=45.6789</url>
<filename size="123456">1.jpeg</filename>
</request>
<request status="ok">
<url>https://maps1.locr.com/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=12.4567&latitude_max=23.5678&longitude_min=34.6789&longitude_max=45.7890</url>
<filename size="234567">2.jpeg</filename>
</request>
<request status="ok">
<url>https://maps1.locr.com/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=13.3456&latitude_max=24.4567&longitude_min=35.5678&longitude_max=46.6789</url>
<filename size="345678">3.jpeg</filename>
</request>
</requests>
</batch>
Das Attribut batch-status kann folgende Werte annehmen:
initialized
running
cancelling
cancelled
completed
Das Attribute request-status kann folgende Werte annehmen:
ok
error
alternative
Abbruch einer URL-Queue (cancel)
Abbruch einer URL-Queue (cancel)
https://maps1.locr.com/api/url_queue.php?action=cancel&id=1
Löschen einer URL-Queue (delete)
Löschen einer URL-Queue (delete)
https://maps1.locr.com/api/url_queue.php?action=delete&id=1
Hinweis: Eine URL-Queue wird nach 30 Tagen automatisch vom Server gelöscht!
Hinweis: Eine URL-Queue wird nach 30 Tagen automatisch vom Server gelöscht!
Herunterladen der erstellten Karten der URL-Queue (download_archive)
Herunterladen der erstellten Karten der URL-Queue (download_archive)
Mit diesem Aufruf können die erstellten Karten als ZIP-Archiv heruntergeladen werden.
https://maps1.locr.com/api/url_queue.php?action=download_archive&id=1
Page updated
Report abuse