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>
    <requests>
        <request>
            <url>/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=12.3456&amp;latitude_max=23.4567&amp;longitude_min=34.5678&amp;longitude_max=45.6789</url>
            <filename>1</filename>
        </request>
        <request>
            <url>/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=12.4567&amp;latitude_max=23.5678&amp;longitude_min=34.6789&amp;longitude_max=45.7890</url>
            <filename>2</filename>
        </request>
        <request>
            <url>/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=13.3456&amp;latitude_max=24.4567&amp;longitude_min=35.5678&amp;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)

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

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

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)

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&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=12.3456&amp;latitude_max=23.4567&amp;longitude_min=34.5678&amp;longitude_max=45.6789</url>
            <filename size="123456">1.jpeg</filename>
        </request>
        <request status="ok">
            <url>https://maps1.locr.com/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=12.4567&amp;latitude_max=23.5678&amp;longitude_min=34.6789&amp;longitude_max=45.7890</url>
            <filename size="234567">2.jpeg</filename>
        </request>
        <request status="ok">
            <url>https://maps1.locr.com/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=13.3456&amp;latitude_max=24.4567&amp;longitude_min=35.5678&amp;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)

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


Comments