Dynamische Abfragezeichenfolgen für REST-API-Aufrufe im Jitterbit Studio erstellen

Einführung

Die Benutzeroberfläche Anforderungsparameter des HTTP v2 Connectors behandelt den häufigsten Fall: eine feste Menge von Parameternamen, deren Werte zur Laufzeit geändert werden. Der Connector kodiert die Werte automatisch in URL-Format. Für eine Einführung in diesen Ansatz siehe Rufen Sie eine REST-API mit dem HTTP v2 Connector auf.

Die skriptbasierte Konstruktion von Abfragezeichenfolgen ist erforderlich, wenn:

• Parameter bedingt basierend auf Quelldaten ein- oder ausgeschlossen werden (zum Beispiel das Hinzufügen eines status-Filters nur, wenn ein Statuswert vorhanden ist).
• Die Parameternamen zur Laufzeit variieren (zum Beispiel filter[contact_type] für einen Datensatztyp und filter[account_type] für einen anderen).
• Die vollständige URL aus mehreren datengestützten Teilen zusammengesetzt wird.

Dieser Leitfaden behandelt drei Techniken zum Erstellen von Abfragezeichenfolgen in Skripten: String-Verkettung für bedingte Parametersätze, Replace für die Substitution fester Vorlagen und URLEncode für die Kodierung von Werten, die Sonderzeichen enthalten.

Eine Abfragezeichenfolge mit String-Verkettung erstellen

Das grundlegende Muster ist:

1. Ein Skript-Schritt, der vor der HTTP v2 GET-Aktivität ausgeführt wird, erstellt die URL und weist sie einer globalen Variablen zu.
2. Das Pfad-Feld der GET-Aktivität verweist auf diese globale Variable.

Die Struktur der Operation ist:

Feste Parameterstruktur mit dynamischen Namen

Wenn die Parametersätze von einer Laufzeitbedingung abhängen (zum Beispiel ein Datensatztyp, der bestimmt, welche Filter gelten), verwenden Sie eine If-Anweisung, um die entsprechende URL für jeden Fall zu erstellen:

// Record type determines which filter parameters apply
If($record_type == "contact",
    $query_url = "/records?type=contact&owner=" & URLEncode($owner_email),
    // Else: account record
    $query_url = "/records?type=account&region=" & URLEncode($region)
);

Optionale Parameter

Wenn eine beliebige Kombination von Parametern vorhanden sein kann oder nicht, erstellen Sie eine params-Zeichenfolge, indem Sie jeden Parameter nur dann anhängen, wenn er einen Wert hat. Durch die Verwendung eines führenden &-Präfixes bei jedem Parameter wird ein nachfolgender Trenner vermieden:

$params = "";
If($start_date != "",
    $params = $params & "&created_after=" & URLEncode($start_date)
);
If($status != "",
    $params = $params & "&status=" & URLEncode($status)
);
If($owner_email != "",
    $params = $params & "&owner=" & URLEncode($owner_email)
);

// Append the query string only when at least one parameter was set.
// Mid(string, 2) strips the leading & from the first parameter.
If($params != "",
    $query_url = "/records?" & Mid($params, 2),
    $query_url = "/records"
);

Mid mit einer Startposition von 2 gibt die Zeichenfolge ab dem zweiten Zeichen zurück und entfernt das führende &, das durch den ersten angehängten Parameter hinterlassen wurde. Die If-Überprüfung schützt den leeren Fall: Wenn keine Parameter gesetzt sind, ist query_url /records ohne nachfolgendes ?.

Werte mit Replace ersetzen

Wenn die URL-Struktur fest ist und nur bestimmte Werte sich ändern, kann eine Vorlagenzeichenfolge mit benannten Platzhaltern sauberer sein als die Verkettung. Definieren Sie die vollständige Abfragezeichenfolge einmal und rufen Sie dann Replace einmal pro Platzhalter auf:

$template = "/contacts?status={status}&created_after={date}&owner={owner}";
$query_url = Replace($template, "{status}", URLEncode($filter_status));
$query_url = Replace($query_url, "{date}",  URLEncode($filter_date));
$query_url = Replace($query_url, "{owner}", URLEncode($owner_email));

Replace ersetzt das erste übereinstimmende Vorkommen der Suchzeichenfolge. Weisen Sie query_url bei jedem Aufruf neu zu, um die Ersetzungen zu verketten. Wählen Sie Platzhalternamen, die anderswo in der URL nicht vorkommen (zum Beispiel, vermeiden Sie {id}, wenn der Pfad bereits {id} als HTTP v2-Pfadparameter enthält).

Parameterwerte mit URLEncode codieren

Beim Erstellen von URLs im Skript rufen Sie URLEncode für jeden Parameterwert auf. Ohne Kodierung brechen Werte, die reservierte Zeichen enthalten, die Anfrage stillschweigend ab:

• Ein Leerzeichen trennt die URL auf der HTTP-Ebene: Der Server erhält einen gekürzten oder fehlerhaften Parameter und gibt typischerweise einen 400-Fehler oder keine Ergebnisse zurück.
• Ein & innerhalb eines Wertes wird als Parametertrennzeichen interpretiert, wodurch der Wert in zwei separate Parameter aufgeteilt wird.
• Andere Zeichen, die kodiert werden müssen, sind #, %, =, + und ?.

Die folgende Tabelle zeigt gängige Beispiele:

Kodieren Sie nicht den Parameternamen, sondern nur den Wert. Parameternamen in REST-APIs sind konventionell ASCII und erfordern keine Kodierung.

Verweisen Sie auf die Abfragezeichenfolge in einer HTTP v2-Aktivität

Geben Sie im Path-Feld der GET-Aktivität die globale Variable ein, die die konstruierte URL enthält (zum Beispiel query_url).

Das Path-Feld folgt diesen Regeln:

• Ein Wert, der mit https:// oder http:// beginnt, wird als vollständige URL behandelt und überschreibt die Basis-URL der Verbindung.
• Ein Wert, der mit / beginnt, wird als Pfadsuffix behandelt und an die Basis-URL angehängt.

Verwenden Sie ein Pfadsuffix (beginnend mit /), wenn die Basisdomäne und die Verbindungsanmeldeinformationen mit anderen Aktivitäten geteilt werden. Verwenden Sie eine vollständige URL-Überschreibung, wenn der Zielendpunkt auf einem anderen Host als der Basis-URL liegt oder wenn keine Verbindung Basis-URL festgelegt ist.

Überprüfen Sie die Integration

1. Bereitstellen und ausführen Sie die Operation.

2. Öffnen Sie das Betriebsprotokoll und bestätigen Sie, dass die GET-Aktivität mit einem erfolgreichen Statuscode abgeschlossen wurde.

3. Um die genaue URL zu inspizieren, die gesendet wurde, fügen Sie am Ende des Pre-Operation-Skripts einen WriteToOperationLog-Aufruf hinzu:

   WriteToOperationLog("query_url: " & $query_url);
   

   Die konstruierte URL erscheint im Protokolleintrag der Skriptstufe. Entfernen Sie die Protokollanweisung, nachdem Sie bestätigt haben, dass die URL korrekt ist.

4. Wenn die API unerwartete Ergebnisse oder einen 400-Fehler zurückgibt, bestätigen Sie, dass URLEncode auf alle Werte angewendet wird, die Leerzeichen oder Sonderzeichen enthalten können. Ein fehlender URLEncode-Aufruf für einen Wert, der & oder = enthält, ist eine häufige Ursache für stille Fehler.