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

Einführung

Die Request Parameters-UI des HTTP v2-Connectors behandelt den häufigsten Fall: einen festen Satz von Parameternamen, deren Werte sich zur Laufzeit ändern. Der Connector kodiert die Werte automatisch URL-codiert. Eine Einführung in diesen Ansatz finden Sie unter REST-API mit dem HTTP v2-Connector aufrufen.

Die Script-basierte Konstruktion von Abfragezeichenfolgen ist erforderlich, wenn:

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

Diese Anleitung behandelt drei Techniken zum Erstellen von Abfragezeichenfolgen in Script: Stringverkettung für bedingte Parametersätze, Replace für Vorlagsubstitution mit fester Struktur und URLEncode zum Kodieren von Werten, die Sonderzeichen enthalten.

Abfragezeichenfolge mit Stringverkettung erstellen

Das grundlegende Muster ist:

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

Die Operationsstruktur ist:

Feste Parameterstruktur mit dynamischen Namen

Wenn der Parametersatz von einer Laufzeitbedingung abhängt (z. B. 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 einen params-String, indem Sie jeden Parameter nur anfügen, wenn er einen Wert hat. Die Verwendung eines führenden &-Präfix für jeden Parameter vermeidet ein nachfolgendes Trennzeichen:

$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 den String ab dem zweiten Zeichen zurück und entfernt das führende &, das vom ersten angefügten Parameter übrig bleibt. Die If-Prü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 festgelegt ist und sich nur bestimmte Werte ändern, kann eine Vorlagenzeichenfolge mit benannten Platzhaltern sauberer sein als 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 erneut zu, um die Ersetzungen zu verketten. Wählen Sie Platzhaltername, die nicht an anderen Stellen in der URL vorkommen (z. B. vermeiden Sie {id}, wenn der Pfad bereits {id} als HTTP v2-Pfadparameter enthält).

Parameterwerte mit URLEncode kodieren

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

• Ein Leerzeichen spaltet die URL auf HTTP-Ebene: Der Server erhält einen abgeschnittenen oder fehlgeformten Parameter und gibt normalerweise einen 400-Fehler oder keine Ergebnisse zurück.
• Ein & in einem Wert wird als Parametertrennzeichen interpretiert und spaltet den Wert in zwei separate Parameter auf.
• Weitere Zeichen, die Kodierung erfordern, sind #, %, =, + und ?.

Die folgende Tabelle zeigt häufige Beispiele:

Codiert nicht den Parameternamen, nur den Wert. Parameternamen in REST-APIs sind üblicherweise ASCII und erfordern keine Codierung.

Die Query String in einer HTTP v2-Aktivität referenzieren

Gib im Feld Path der GET-Aktivität die globale Variable ein, die die konstruierte URL enthält (beispielsweise query_url).

Das Feld Path folgt diesen Regeln:

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

Nutze ein Pfad-Suffix (beginnt mit /), wenn die Basisdomäne und Verbindungsanmeldedaten mit anderen Aktivitäten gemeinsam genutzt werden. Nutze eine vollständige URL-Überschreibung, wenn sich der Zielendpunkt auf einem anderen Host als die Base URL befindet, oder wenn keine Base URL für die Verbindung festgelegt ist.

Die Integration überprüfen

1. Stelle den Betrieb bereit und führe ihn aus.

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

3. Um die genaue gesendete URL zu überprüfen, füge einen WriteToOperationLog-Aufruf am Ende des Pre-Operation-Scripts hinzu:

   WriteToOperationLog("query_url: " & $query_url);
   

   Die konstruierte URL wird im Betriebsprotokolleintrag für den Script-Schritt angezeigt. Entferne die Log-Anweisung, nachdem bestätigt wurde, dass die URL korrekt ist.

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