Mit dem HttpDataProvider können Sie auf beliebig konfigurierbare HTTP/HTTPS-Endpunkte zugreifen. In der einfachsten Konfigurationsart gibt man eine Zieladresse an und wandelt dann die resultierenden Daten in Kontakte um. Da viele Dienste eine Authentifizierung voraussetzen, ist es über den Provider möglich, eine Schrittfolge von HTTP-Anfragen zu definieren, um so z. B. "Access-Tokens" oder andere Daten zu holen und diese für weitere HTTP-Anfragen weiterzuverwenden.

Konfiguration

Neben der Mapping- und SearchParameters-Konfiguration, welche alle DataProvider der Datenschnittstelle benötigen, kann der HttpDataProvider über das Configuration-Element konfiguriert werden:

<HttpDataProvider DisplayName="Kundenadressen">
  <Configuration>
    ...
  </Configuration>
  ...
</HttpDataProvider>

Configuration Unter diesem Punkt wird die Abfolge an HTTP Anfragen definiert.

Secret Um Klartextpasswörter in Konfigurationen zu vermeiden, können Secrets als <Secret Name="..." Value="{c[...]}" /> erfasst werden. Zur Laufzeit wird das Passwort entschlüsselt und kann als Platzhalter für Requests verwendet werden.
Step Ein Step umfasst jeweils Request und Response. Es können bliebig viele "Steps" definiert werden. Während jedes Schrittes können Properties oder Contacts in die Resultatliste aufgenommen werden.
- Request Über dieses Element wird die HTTP Anfrage gebaut.
  - Method (Attribut) HTTP Methode, welche genutzt werden soll (GET, POST, ...)
  - Url Ziel URL des Aufrufs. In der URL können Platzhalter über diese Schreibweise genutzt werden: {Placeholder}. Platzhalter werden stets URL-Encoded.
  - Header Es können beliebig viele HTTP Header angegeben werden. Es können ebenfalls Platzhalter über den {Placeholder}-Syntax genutzt werden.
  - Body Es kann ein Body definiert werden. Es können ebenfalls Platzhalter über den {Placeholder}-Syntax genutzt werden. Es findet hierbei kein Encoding statt.
  - FakeResponse Um einen Endpunkt zu testen, kann das Element FakeResponse genutzt werden um einen konfigurierbaren Rückgabewert zu definieren.
  - Polling Über diese Funktion kann der Request angewiesen werden mehrfach auf die URL in einem Interval zuzugreifen bis ein bestimmter Zielwert mittels eines JsonPath bzw. XPath gefunden wurde oder die Maximalzeit (MaxDuration) erreicht wurde.
- Response Über die Response kann auf die HTTP Antwort zugegriffen werden. Ein Response kann entweder eine oder mehrere Property-Elemente erzeugen oder ein Mapping auf die Daten vornehmen.
  - Hinweis: Dieses Element ist optional, falls nur ein Request ausgelöst werden soll.
  - Property Über dieses Element kann man mittels eines JsonPath oder ein XPath einen bestimmten Wert aus der HTTP Antwort herauslesen. Der Wert steht dann über die {Placeholder} für weitere Anfragen unter dem konfigurierten Namen zur Verfügung.
  - Data Die eigentlichen Daten werden über dieses Element gesucht. Hierbei muss ein JsonPath oder ein XPath angegeben werden. Die Daten werden dann über das Mapping für das Schema des Object / ObjectCollection umgewandelt.

Polling

Der HttpDataProvider kann mehrere Schritte (Step) beinhalten. Theoretisch ist es z.B. möglich mit einem Step einen Aufruf zu starten und im nächsten Step auf das Ergebnis zuzugreifen.
Falls das Ergebnis aber nicht direkt zur Verfügung steht, muss auf das Ergebnis gewartet werden.
Hierfür kann das Polling-Feature genutzt werden:

...
<Step>
  <Request Method="Get">
    <Url><![CDATA[https://sampleservice.local/api/reports/status/{ReportId}]]></Url>
    <Polling Interval="500" MaxDuration="30000" JsonPath="$.status" SuccessValue="Completed"/>
    <!-- Interval in ms / MaxDuration in ms -->
  </Request>
  <Response>
    <Data JsonPath="$">
      <Mapping>
        <Map Source="id" Target="FirstName"/>
      </Mapping>
    </Data>
  </Response>
</Step>
...

Die Ziel URL muss auch beim Polling erreichbar sein und kein HTTP Fehler zurückliefern.

Interval Definiert die Zeitabstände in der der Request auf die Url ausgeführt wird.
MaxDuration Definiert die maximale Zeit, danach wird der Request abgebrochen und ein Fehler wird zurück gegeben.
JsonPath und XPath Angabe eines JsonPath bzw. XPath um die Erfolgsbedingung zu finden.
SuccessValue Angabe der erfolgreichen Wertes, welches das Polling beendet.

Beispiel-XML-Konfiguration

“Tel-Search”-Beispiel:

<HttpDataProvider DisplayName="TelSearch">
  <SearchParameters>
    <Text Id="What" Label="Suchbegriff" />
  </SearchParameters>
  <Configuration>
    <Step>
      <Request Method="Get">
        <Url><![CDATA[https://tel.search.ch/api/?was={What}&key=[Key]&maxnum=100]]></Url>
      </Request>
      <Response>
        <Data XPath="*[local-name()='feed']/*[local-name()='entry']">
          <Mapping>
            <Map Source="*[local-name()='name']" Target="CompanyName" />
            <Map Target="Street">
              <Map.SourceExpression><![CDATA[
                function main()
                {
                  const street = source("*[local-name()='street']");
                  const streetno = source("*[local-name()='streetno']");
                  return street + " " + streetno; 
                }
              ]]></Map.SourceExpression>
            </Map>
            <Map Source="*[local-name()='zip']" Target="PostalCode" />
            <Map Source="*[local-name()='city']" Target="City" />
            <Map SourceValue="CH" Target="Country" />
          </Mapping>
        </Data>
      </Response>
    </Step>
  </Configuration>
</HttpDataProvider>