Migracje SDK
Migracja do SDK 4.0 i interfejsu API sesji v3
Przenieś kod w Pythonie i PHP z wywołań sesji flow w wersji v2 na v3, które przesyła identyfikator sesji w nagłówku.
Interfejs API sesji v2 kończy życie 30 listopada 2026 r.
SDK 4.0.0 deprecjonuje wywołania sesji flow v2, takie jak create_flow_session, invoke_flow_response i poll_flow_response. Trasy sesji v2 kończą życie 30 listopada 2026 r. Przenieś swój kod na wywołania v3 opisane na tej stronie, zanim to nastąpi.
Wersja 4.0.0 SDK FlowHunt dla Pythona i PHP dodaje interfejs API sesji flow v3. Przejście na niego sprawia, że identyfikatory sesji czatu nie trafiają do adresów URL, a większość pracy polega na zmianie nazw metod. Ta strona pokazuje, co się zmieniło, które wywołania trzeba przemianować oraz kod przed i po.
Co się zmieniło#
Wywołania sesji v3 przekazują identyfikator sesji w nagłówku X-FH-Session-Id, nigdy w adresie URL. Treść żądań i odpowiedzi jest taka sama jak w v2. Trasy sesji v2 są przestarzałe i kończą życie 30 listopada 2026 r.
W v2 każde wywołanie czatu umieszcza identyfikator sesji w ścieżce, na przykład /v2/flows/sessions/{session_id}/invoke. Identyfikator sesji to jedyne poświadczenie, jakie ma anonimowa sesja czatu, a adresy URL trafiają do logów dostępu, logów proxy, historii przeglądarki i nagłówków Referer. Nagłówek nie.
Instalacja 4.0.0#
Python
Pakiet na PyPI to flowhunt.
pip install --upgrade "flowhunt>=4,<5"PHP
Pakiet na Packagist to flowhunt/flowhunt-php-sdk. Wymaga PHP 8.1 lub nowszego.
composer require flowhunt/flowhunt-php-sdk:^4.0Migracja w czterech krokach#
Zaktualizuj pakiet
Zainstaluj 4.0.0 w sposób pokazany powyżej. Twoje istniejące wywołania v2 nadal działają po aktualizacji, więc możesz przenosić wywołania jedno po drugim. Zdąż przed 30 listopada 2026 r.
Zmień nazwę każdego wywołania sesji
Dodaj
_v3do nazwy metody w Pythonie lubV3do nazwy w PHP. Mapowanie metod zawiera listę wszystkich par.Przekaż identyfikator sesji jako argument nagłówka
Argument identyfikatora sesji to teraz
x_fh_session_id. W Pythonie przekazuj go jako argument nazwany. W PHP trzy metody przyjmują go jako drugi argument, a nie pierwszy. Zobacz Zmieniona kolejność argumentów w trzech metodach.Sprawdź usunięte metody
Jeśli wywołujesz którąkolwiek z metod usuniętych w 4.0.0, przełącz się na zamiennik lub usuń wywołanie.
Mapowanie metod#
Metody Pythona znajdują się w flowhunt.FlowsApi, a te same metody v3 istnieją również w flowhunt.V3Api. Metody PHP znajdują się w FlowHunt\Api\FlowsApi.
| Co | HTTP v2 | HTTP v3 (identyfikator sesji w X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Rozpocznij sesję flow (klucz API) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Rozpocznij sesję chatbota (anonimowo) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Wyślij wiadomość | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Odpytuj o zdarzenia | POST /v2/flows/sessions/{id}/invocation_response/{from_timestamp} | POST /v3/flows/sessions/invocation_response/{from_timestamp} | poll_flow_response → poll_flow_response_v3 | pollFlowResponse → pollFlowResponseV3 |
| Anuluj uruchomienie | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Wróć do poprzedniego anchora | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Wywołaj hook czatu | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Wznów oczekujący hook | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Ustaw zmienne flow | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Wyświetl załączniki | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Prześlij załącznik | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Usuń załącznik | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Opinia o wiadomości | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Odczytaj artefakt | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Wyszukiwanie w trakcie pisania (nowe, brak w v2) | brak | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
Pobieranie załącznika (GET /v2/flows/sessions/{id}/attachments/{file_id}) nie ma wersji v3. To wywołanie z panelu wymagające zalogowania i nie jest częścią tej migracji.
Tylko dwa wywołania tworzenia wymagają Twojego klucza API. from_flow/create rozpoczyna sesję dla flow w Twoim workspace i wymaga klucza. create to anonimowa sesja chatbota używana przez osadzony widget czatu, więc nie wymaga klucza. Oba zwracają session_id i created_at z kodem HTTP 201. Każde inne wywołanie sesji v3 wymaga tylko nagłówka X-FH-Session-Id.
Na razie przesyłaj załączniki przez HTTP
W 4.0.0 upload_attachments_v3 i uploadAttachmentsV3 nie potrafią wysłać pliku. API zwraca 422 „Expected UploadFile”, a metoda Pythona odrzuca bajty przed wysłaniem żądania. Metody przesyłania z 3.x mają ten sam problem. Dopóki nie zostanie to naprawione, wysyłaj plik jako multipart/form-data do POST /v3/flows/sessions/attachments z nagłówkiem X-FH-Session-Id. Zakładka HTTP poniżej pokazuje to wywołanie.
Przed i po#
Ten przykład rozpoczyna sesję dla opublikowanego flow, wysyła „Hello” i wypisuje odpowiedź flow. Każda zakładka pokazuje najpierw kod 3.x, a potem kod 4.0, który uruchomiliśmy przeciwko https://api.flowhunt.io. Kod 4.0 odczytuje klucz API, identyfikator workspace i identyfikator flow ze zmiennych środowiskowych FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID i FLOWHUNT_FLOW_ID.
Python
session = flows.create_flow_session(workspace_id, flowhunt.FlowSessionCreateFromFlowRequest(flow_id=FLOW_ID))
invocation = flows.invoke_flow_response(session.session_id, flowhunt.FlowSessionInvokeRequest(message="Hello"))
events = flows.poll_flow_response(session.session_id, from_timestamp)import os
import time
import flowhunt
config = flowhunt.Configuration(host="https://api.flowhunt.io")
config.api_key["APIKeyHeader"] = os.environ["FLOWHUNT_API_KEY"]
with flowhunt.ApiClient(config) as client:
flows = flowhunt.FlowsApi(client)
session = flows.create_flow_session_v3(
workspace_id=os.environ["FLOWHUNT_WORKSPACE_ID"],
flow_session_create_from_flow_request=flowhunt.FlowSessionCreateFromFlowRequest(
flow_id=os.environ["FLOWHUNT_FLOW_ID"]
),
)
session_id = session.session_id # trzymaj w tajemnicy, nigdy nie loguj
invocation = flows.invoke_flow_response_v3(
x_fh_session_id=session_id,
flow_session_invoke_request=flowhunt.FlowSessionInvokeRequest(message="Hello"),
)
since, seen, answered = int(invocation.created_at), set(), False
for _ in range(60):
time.sleep(2)
events = flows.poll_flow_response_v3(
x_fh_session_id=session_id, from_timestamp=since
)
new_events = [e for e in events if e.event_id not in seen]
for event in new_events:
seen.add(event.event_id)
since = max(since, int(float(event.created_at_timestamp)) - 1)
if event.action_type == "failed":
raise RuntimeError("Uruchomienie flow nie powiodło się")
if event.event_type == "ai" and event.action_type == "message":
print(event.metadata.to_dict()["message"])
answered = True
if answered and not new_events:
breakPHP
$session = $flows->createFlowSession($workspaceId, $request);
$invocation = $flows->invokeFlowResponse($session->getSessionId(), $invokeRequest);
$events = $flows->pollFlowResponse($session->getSessionId(), $fromTimestamp);<?php
require 'vendor/autoload.php';
$config = FlowHunt\Configuration::getDefaultConfiguration()
->setHost('https://api.flowhunt.io')
->setApiKey('Api-Key', getenv('FLOWHUNT_API_KEY'));
$flows = new FlowHunt\Api\FlowsApi(new GuzzleHttp\Client(), $config);
$session = $flows->createFlowSessionV3(
getenv('FLOWHUNT_WORKSPACE_ID'),
new FlowHunt\Model\FlowSessionCreateFromFlowRequest(['flow_id' => getenv('FLOWHUNT_FLOW_ID')])
);
$sessionId = $session->getSessionId(); // trzymaj w tajemnicy, nigdy nie loguj
$invocation = $flows->invokeFlowResponseV3(
$sessionId,
new FlowHunt\Model\FlowSessionInvokeRequest(['message' => 'Hello'])
);
$since = (int) $invocation->getCreatedAt();
$seen = [];
$answered = false;
for ($i = 0; $i < 60; $i++) {
sleep(2);
// Zwróć uwagę na kolejność: najpierw znacznik czasu, potem identyfikator sesji.
$events = $flows->pollFlowResponseV3($since, $sessionId);
$newEvents = array_filter($events, fn ($e) => !isset($seen[$e->getEventId()]));
foreach ($newEvents as $event) {
$seen[$event->getEventId()] = true;
$since = max($since, (int) $event->getCreatedAtTimestamp() - 1);
if ($event->getActionType() === 'failed') {
throw new RuntimeException('Uruchomienie flow nie powiodło się');
}
if ($event->getEventType() === 'ai' && $event->getActionType() === 'message') {
echo $event->getMetadata()->getMessage(), PHP_EOL;
$answered = true;
}
}
if ($answered && !$newEvents) {
break;
}
}HTTP
Tylko wywołanie tworzenia wysyła klucz API. Każde kolejne wywołanie wysyła identyfikator sesji w nagłówku X-FH-Session-Id.
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/from_flow/create?workspace_id=$WORKSPACE_ID" \
-H "Api-Key: $FLOWHUNT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"flow_id\": \"$FLOW_ID\"}"curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invoke" \
-H "X-FH-Session-Id: $SESSION_ID" \
-H "Content-Type: application/json" \
-d '{"message": "Hello"}'curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
-H "X-FH-Session-Id: $SESSION_ID"curl -X POST "https://api.flowhunt.io/v3/flows/sessions/attachments" \
-H "X-FH-Session-Id: $SESSION_ID" \
-F "file=@invoice.jpg;type=image/jpeg"Wcześniej identyfikator sesji był częścią każdej ścieżki, na przykład /v2/flows/sessions/$SESSION_ID/invoke. Wywołanie v3 bez nagłówka zwraca 401.
Jak działa odpytywanie#
from_timestampto milisekundy od początku epoki. Odpytanie zwraca zdarzenia, którychcreated_at_timestampjest ściśle większy.- Zacznij od
created_atz odpowiedzi na wywołanie invoke, która jest wartością w milisekundach wysłaną jako ciąg znaków, więc przekonwertuj ją na liczbę całkowitą. Użyj0, aby pobrać całą sesję. Nie używajcreated_atz odpowiedzi tworzenia, która jest datą i godziną, a nie milisekundami. - Po każdym odpytaniu przesuń
from_timestampna wartośćcreated_at_timestampnajnowszego zdarzenia minus 1 i pomiń zdarzenia, którychevent_idjuż widziałeś. Zdarzenia utworzone w tej samej milisekundzie mogą nadejść w różnych odpytaniach. Widget czatu FlowHunt odpytuje w ten sam sposób. - Każde zdarzenie ma
event_type(ai,humanlubsystem),action_type(message,loading,tool_call,failed,hook_waiting_for_inputi inne) orazmetadata. Tekst odpowiedzi znajduje się wmetadata.messagezdarzeńmessagetypuai.
FlowHunt nie wysyła osobnego zdarzenia „uruchomienie zakończone”. Gdy uruchomiliśmy próbki na jednostopniowym flow, odpytanie zwróciło zdarzenie system typu loading, potem jedno ai message z odpowiedzią i nic więcej. Dlatego próbki zatrzymują się na pierwszym odpytaniu, które po nadejściu odpowiedzi nie przynosi nowych zdarzeń, i zgłaszają wyjątek przy failed. Jeśli Twój flow wysyła kilka wiadomości lub czeka na dane wejściowe z hook_waiting_for_input, ustal własny warunek zakończenia.
Zmieniona kolejność argumentów w trzech metodach#
Zmień kolejność tych trzech wywołań
Metody v3 umieszczają parametry ścieżki przed nagłówkiem identyfikatora sesji. W PHP, a w Pythonie przy przekazywaniu argumentów pozycyjnie, te trzy wywołania kończą się błędem typu albo po cichu wysyłają niewłaściwe wartości, jeśli nie zmienisz ich kolejności.
| v2 | v3 |
|---|---|
pollFlowResponse($session_id, $from_timestamp) | pollFlowResponseV3($from_timestamp, $x_fh_session_id) |
deleteAttachment($session_id, $file_id) | deleteAttachmentV3($file_id, $x_fh_session_id) |
getArtefactContent($session_id, $artefact_id) | getArtefactContentV3($artefact_id, $x_fh_session_id) |
W Pythonie przekazuj wszędzie argumenty nazwane, na przykład x_fh_session_id=session_id, a kolejność przestaje mieć znaczenie. Python 4.0 sprawdza też typy argumentów, więc from_timestamp musi być typu int. Przekazanie ciągu "0" powoduje błąd pydantic ValidationError.
Inne zmiany łamiące kompatybilność w 4.0.0#
Te metody były w 3.19.1 i zniknęły w 4.0.0, ponieważ punkty końcowe API za nimi zostały usunięte lub zmienione. Nazwy metod PHP to wersje camelCase nazw pythonowych, na przykład get_available_models staje się getAvailableModels.
| Usunięta metoda | Punkt końcowy | Co zrobić |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Usuń wywołanie. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Usuń wywołanie. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Usuń wywołania. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Usuń wywołanie. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Wywołaj start_export_csv (POST, ta sama ścieżka), a następnie get_export_csv_status (GET .../export-csv/{task_id}). |
Usunięto także metody dla kanału Zendesk, płatności Shopify, Replicate i webhooków pingback SERP. To przychodzące webhooki dla serwerów FlowHunt, a nie wywołania z Twojego kodu.
Trzymaj identyfikator sesji w tajemnicy#
Identyfikator sesji to poświadczenie
Każdy, kto ma identyfikator sesji, może odczytać tę rozmowę i ją kontynuować. Nie zapisuj go w logach, nie umieszczaj w adresach URL ani ciągach zapytań i nie wysyłaj do narzędzi analitycznych. Traktuj go jak krótkotrwałe hasło.
A co z v2?#
Trasy sesji v2 są przestarzałe od czasu SDK 4.0.0 i kończą życie 30 listopada 2026 r. Do tego czasu nadal działają i są oznaczone jako przestarzałe w dokumentacji API. SDK 4.0.0 nadal zawiera metody v2. W Pythonie wywołanie jednej z nich zgłasza DeprecationWarning. W PHP są oznaczone w kodzie jako @deprecated, co wskaże Twoje IDE lub analiza statyczna.