====== sendJSON(), sendPOST() und sendXML() ======

Der Befehl ''sendJSON()'' sendet eine HTTP-Anfrage an die angegebene URL und gibt die Antwort des Servers zurück.

''mixed **sendJSON**(string //URL//, array //Daten//, [array //Header//], [int //Timeout//])''\\
''mixed **sendPOST**(string //URL//, array //Daten//, [array //Header//], [int //Timeout//])''\\
''mixed **sendXML**(string //URL//, string //XML//, [array //Header//], [int //Timeout//])''

  * //URL//\\ Die URL, an welche die HTTP-Anfrage geschickt werden soll.
  * //Daten//\\ Die Daten, welche im JSON- oder POST-Format übermittelt werden sollen.
  * //XML//\\ Ein XML-String, welcher übermittelt werden soll.
  * //Header//\\ Ein Array mit zusätzlichen HTTP-Header-Feldern.
  * //Timeout//\\ Zeit bis zum Abbruch der Anfrage in Sekunden (Standard: 5 Sekunden, erlaubt sind Werte zwischen 1 und 30)

**Warnung:** Die Anfrage wird synchron durchgeführt, das bedeutet, dass sie die Ladezeit der Fragebogen-Seite um die Zeit verzögert bis der angefragte Server eine Antwort sendet. Die Anfrage wird abgebrochen, wenn die Ladezeit mehr als 5 Sekunden (beziehungsweise den als //Timeout// angegeben Wert) in Anspruch nimmt.

**Hinweis:** Falls Sie den Timeout erhöhen, dann stellen Sie sicher, dass auf der Fragebogenseite klar erkennbar ist, dass es nach dem Klick auf "Weiter" länger dauert. Sie können zum Beispiel den Weiter-Knopf per JavaScript nach dem Klick durch ein "Bitte warten" ersetzen oder Sie können eine Seite einfügen, die nur eine Warte-Animation zeigt, die per JavaScript direkt abgeschickt wird und die dann zu der seite mit ''sendJSON()'' führt.

**Hinweis:** Die Anzahl der Anfragen ist begrenzt (s. [[#einschraenkungen|Einschränkungen]]).

**Hinweis:** Wenn die Druckansicht eines Interviews erstellt wird, liefern die Funktionen immer den Fehlercode ''null'' beziehungsweise ''false''.

===== Rückgabewert sendJSON() =====

Wenn die Anfrage aufgrund eines Fehlers nicht verarbeitet werden konnte, wird ''null'' zurückgegeben.

Wenn die Gegenstelle eine Antwort im JSON-Format sendet, wird diese als Array zurückgegeben.

Ansonsten wird die Antwort des Servers als ''string'' zurückgegeben.
   
   
===== Rückgabewert sendPOST() =====

Wenn die Anfrage aufgrund eines Fehlers nicht verarbeitet werden konnte, wird ''false'' zurückgegeben.

Ansonsten wird die Antwort des Servers als ''string'' zurückgegeben.


===== Rückgabewert sendXML() =====

Wenn die Anfrage aufgrund eines Fehlers nicht verarbeitet werden konnte, wird ''false'' zurückgegeben.

Wenn der Server gültige XML-Daten übermittelt, werden diese dekodiert und als Array zurückgegeben, wobei jedes XML-Tag in einem Array mit den folgenden Schlüsseln repräsentiert wird:

  * string ''%%'name'%%'' -- Attribut-Name
  * array ''%%'attr'%%'' -- Attribute im XML-Tag
  * string ''%%'content'%%'' -- Eventueller Text-Inhalt des XML-Tags
  * array ''%%'children'%%'' -- Eventuelle Kind-Elemente des XML-Tags

Ansonsten wird die Antwort des Servers als ''string'' zurückgegeben.


===== Einschränkungen =====

  * In einem Befragungsprojekt können innerhalb von 24 Stunden maximal 1000 Anfragen versendet werden.
  * Innerhalb eines Interviews können maximal 20 Anfragen verschickt werden, innerhalb einer Seite maximal 2 Anfragen.
  * Es können keine Anfragen an den Befragungsserver selbst gesendet werden.


===== Beispiel =====

<code php>
$data = sendJSON('https://example.com', [
  'q' => 'reflect',
  'd' => 'SoSci Survey'
]);
debug($data);
</code>

<code php>
$data = sendJSON('https://api.openai.com/v1/chat/completions', [
    'model' => 'gpt-3.5-turbo',
    'messages' = [
        [
            'role' => 'user',
            'content' => 'Hello!'
        ]
    ]
], [
    'Authorization' =>  'Bearer 12345678990'
]);
debug($data);
</code>


===== Testen =====

Falls die Gegenstelle nicht so reagiert, wie man das erwarten würde, sollten Sie zunächst Ihre Anfrage prüfen.

SoSci Survey stellt unter [[https://www.soscisurvey.de/tools/post-monkey.php]] ein kleines Script zur Verfügung. Sie erhalten dort eine URL, an welche Sie eine Anfrage (Request) übermitteln können. Anschließend können Sie den Inhalt der Anfrage überprüfen.

Wenn die Anfrage Ihrer Meinung nach korrekt ist, sehen Sie sich die Antwort an. Am einfachsten senden Sie die Anfrage einmal über die Entwickler-Tools Ihres Browsers ([[:de:general:browser-tools]]) an die API. Alternativ können Sie den Rückgabewert der Funktion mittels ''debug()'' genauer ansehen (siehe oben).