Url-Queue

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

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:

Authentifizierung

2. Die Vorgabe des zu verwendenden Servers, z.B.: http://maps1.locr.com

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>

<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>

</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>

</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>

</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)

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>

Optionale Parameter:

HTTP-Formular Beispiel:

<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

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>

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"?>

<details>invalid parameter value "stat" for "action"</details>

</error>

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"?>

<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>

</request>

<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>

</request>

<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>

</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)

https://maps1.locr.com/api/url_queue.php?action=cancel&id=1

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!

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