Sfoglia la documentazione
Guide
Eseguire le attività CLI dell'applicazione o dell'agente su Linux o Docker, quindi verificare l'accesso e il riutilizzo dei risultati dopo un riavvio.
In questa pagina
1. Scegli il runtime
Utilizzare un host Linux con Bash e jq e una chiave API con autorizzazione google_search. Eseguire la configurazione come utente OS che eseguirà l'attività. Creare questa cartella di attività privata per i passaggi 1–4; le etichette dei file mostrano qualsiasi sottocartelle.
umask 077
mkdir -p "$HOME/flashdata-tasks/deployment-check"
cd "$HOME/flashdata-tasks/deployment-check"Installare il nativo CLI prima. Eseguire il comando -v flashdata per trovare il suo percorso assoluto, quindi impostare FLASHDATA_BIN su quel percorso in runtime.sh. Impostare il nome del profilo e il percorso di stato persistente una volta qui, quindi salvare il file.
# runtime.sh — edit the executable and persistent state paths.
export FLASHDATA_BIN=/usr/local/bin/flashdata
export FLASHDATA_PROFILE=research
export FLASHDATA_STATE_DIR="$HOME/.local/state/flashdata-research"
run_flashdata() {
env -u FLASHDATA_API_KEY "$FLASHDATA_BIN" "$@" \
--profile "$FLASHDATA_PROFILE" \
--state-dir "$FLASHDATA_STATE_DIR"
}Su un host Linux Docker con curl, tar e sha256sum, scarica il pinned CLI per la CPU host. Salvare image/Dockerfile e image/.dockerignore di seguito, costruire l'immagine, quindi salvare runtime.sh. L'aiutante viene eseguito come UID/GID e monta le cartelle di stato e di attività in ogni nuovo contenitore.
(
set -euo pipefail
case "$(uname -m)" in
x86_64) arch=amd64 ;;
aarch64|arm64) arch=arm64 ;;
*) echo 'Use a Linux amd64 or arm64 host.' >&2; exit 1 ;;
esac
mkdir -p image
cd image
archive="flashdata_1.2.1_linux_$arch.tar.gz"
base='https://github.com/flashdatadev/flashdata-cli/releases/download/v1.2.1'
curl --fail --show-error --location "$base/$archive" -o "$archive"
curl --fail --show-error --location "$base/SHA256SUMS" -o SHA256SUMS
awk -v file="$archive" '$2 == file { print }' SHA256SUMS | sha256sum -c -
tar -xzf "$archive" flashdata
)FROM debian:bookworm-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY --chmod=0755 flashdata /usr/local/bin/flashdata
USER 10001:10001
ENTRYPOINT ["/usr/local/bin/flashdata"]*
!Dockerfile
!flashdatadocker build --tag flashdata-runtime:1.2.1 ./image
docker run --rm flashdata-runtime:1.2.1 --version# runtime.sh — use the local image built above.
export FLASHDATA_IMAGE='flashdata-runtime:1.2.1'
export FLASHDATA_PROFILE=research
export FLASHDATA_STATE_DIR="$HOME/.local/state/flashdata-research"
run_flashdata() {
docker run --rm -i --user "$(id -u):$(id -g)" \
--env FLASHDATA_API_KEY= \
--mount "type=bind,src=$FLASHDATA_STATE_DIR,dst=/state" \
--mount "type=bind,src=$PWD,dst=/work" --workdir /work \
--entrypoint /usr/local/bin/flashdata "$FLASHDATA_IMAGE" \
"$@" --profile "$FLASHDATA_PROFILE" --state-dir /state
}Controllare l'orario di esecuzione selezionato
run_flashdata è l'aiutante salvato in runtime.sh; tutti i comandi successivi utilizzano il suo profilo e la directory di stato. Ignora FLASHDATA_API_KEY in modo che una chiave ambiente non possa sostituire il profilo salvato. Aspettatevi le versioni CLI e jq.
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version2. Installare l'accesso del proprietario una volta
Se il profilo ha già accesso proprietario, saltare l'importazione e eseguire il controllo qui sotto. In caso contrario, montare un file segreto chiave proprietario leggibile dall'utente del servizio e sostituire il percorso di esempio con la sua posizione. L'importazione lo legge attraverso stdin; Docker non lo copia nell'immagine.
export FLASHDATA_KEY_FILE='/run/secrets/flashdata_api_key'set -euo pipefail
. ./runtime.sh
: "${FLASHDATA_KEY_FILE:?Set the path to your mounted owner-key secret}"
run_flashdata auth login --api-key-stdin --non-interactive \
< "$FLASHDATA_KEY_FILE"
run_flashdata auth status --json --non-interactiveConfermare l'account e il permesso
Il controllo stampa l'account ID, le fonti consentite e la protezione delle credenziali, quindi true. Confermare l'account ID è il proprietario previsto prima di continuare. access.json rimane nella cartella di compito per l'ispezione.
set -euo pipefail
umask 077
. ./runtime.sh
run_flashdata auth status --json --non-interactive > access.json
jq '{accountId: .data.identity.identity.accountId,
sources: .data.identity.permittedSources,
credentialProtection: .data.credentialProtection}' access.json
jq -e '.ok and .data.accessVerified
and (.data.identity.identity.recurringAllowed == true)
and (.data.identity.permittedSources | index("google_search") != null)' access.jsonArchiviazione Credenziale e file persistenti
Ispezionare data.credentialProtection in auth status. Linux può utilizzare un servizio segreto sbloccato; un host senza testa o il contenitore sopra può utilizzare un file di testo semplice proprietario. Tenere la directory statale privata e persistente. Fornire l'utente distribuito separatamente dal profilo crittografato del computer portatile.
| Continua | Località |
|---|---|
| Credenziali e diario di esecuzione | FLASHDATA_STATE_DIR |
| Input, ricevute e risultati | La cartella delle attività; montata come /work in Docker. |
3. Convalida la richiesta e il costo
Salvare request.json accanto a runtime.sh. Il seguente controllo convalida l'accesso ricorrente e la richiesta, legge i prezzi correnti e lo confronta con il saldo disponibile. Non invia ricerca e non riserva crediti. Continuare solo quando il filtro stampa true.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}set -euo pipefail
umask 077
. ./runtime.sh
run_flashdata account balance --json --non-interactive > balance.json
run_flashdata query --input request.json --mode realtime --dry-run --recurring \
--run-id deployment-first-task --json --non-interactive > preflight.json
jq -e --slurpfile balance balance.json '
.ok and .data.dryRun and .data.estimateAvailable
and ($balance[0].ok == true)
and any(.data.estimate.prices[]?;
.source == "google_search" and .available == true
and (.estimatedCredits | type == "number")
and ($balance[0].data.availableCredits | type == "number")
and .estimatedCredits <= $balance[0].data.availableCredits)
' preflight.json4. Esegui una volta e verifica il riutilizzo
Salva deployment-check.sh qui sotto. Con una nuova esecuzione ID, la prima esecuzione presenta una ricerca a pagamento; la seconda avvia un nuovo processo e legge il risultato salvato. Se questo ID già completato nello stesso profilo, entrambi tenta di riutilizzarlo.
Salvare deployment-check.sh
Creare deployment-check.sh accanto a runtime.sh e request.json nella cartella di attività privata sull'host. Copia lo script completo qui sotto e salvalo.
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
. ./runtime.sh
attempt=$(mktemp -d ./deployment-check.XXXXXX)
printf 'Attempt files: %s\n' "$attempt" >&2
cp -- request.json "$attempt/request.json"
if ! run_flashdata query --input "$attempt/request.json" --mode realtime --recurring \
--run-id deployment-first-task --timeout 2m --json --non-interactive \
--output "$attempt/result.json" \
> "$attempt/receipt.json" 2> "$attempt/error.json"; then
cat "$attempt/error.json" >&2
exit 1
fi
jq -e '.ok == true' "$attempt/receipt.json" >/dev/null
jq -e '.source == "google_search" and .status == "done"
and (.results[0].organic | type == "array")' "$attempt/result.json" >/dev/null
jq '{runId, cached, usage}' "$attempt/receipt.json"
printf 'Saved result: %s\n' "$attempt/result.json"Eseguire il controllo salvato due volte
Eseguire da quella cartella di attività host come lo stesso utente di servizio. Entrambi i processi caricano lo runtime.sh salvato nella fase 1.
# A new run ID submits one paid search; a completed ID reuses its result.
bash deployment-check.sh
# New process; Docker uses a new container with the same mounts.
# Same account, input and state: cached: true, no new search.
bash deployment-check.shVerificare la seconda ricevuta
Per una nuova esecuzione, aspettatevi cache: false, quindi cache: true. Ogni tentativo stampa la sua cartella deployment-check.XXXXXX e salva request.json, receipt.json e error.json, più result.json sul successo. La ricevuta della cache riporta l'utilizzo originale. Un tentativo fallito mantiene i suoi file per il recupero.
{
"ok": true,
"runId": "deployment-first-task",
"cached": true
}Leggi il risultato di ricerca salvato
Impostare ATTEMPT_DIR alla seconda cartella di successo stampata sopra, ad esempio esportare ATTEMPT_DIR='./deployment-check.ABC123'. Questi comandi leggono solo i file locali.
# Use one attempt folder printed by deployment-check.sh.
: "${ATTEMPT_DIR:?Set a saved deployment-check.XXXXXX folder}"
jq '{runId, cached, usage}' "$ATTEMPT_DIR/receipt.json"
jq '.results[0].organic[] | {title, link, snippet}' "$ATTEMPT_DIR/result.json"Spostarsi da un controllo di distribuzione a un'attività ricorrente
Questo assegno ha un funzionamento fisso ID. Per il lavoro ricorrente, dare ad ogni evento previsto il proprio ID e mantenere il tempo di esecuzione selezionato, account, snapshot di input e supporti di stato. Adapt il comando di query del corridore ricorrente per utilizzare run_flashdata in modo che le attività Docker rimangano all'interno del contenitore.
Controllare l'accesso da GitHub Azioni
Utilizzare un corridore Linux affidabile e persistente con Bash, jq e il profilo CLI già installato sotto l'utente OS del runner. Salvare questo flusso di lavoro nel repository della tua applicazione. Controlla l'host CLI senza eseguire un'attività pagata.
- Assegna l'etichetta flashdata-research a quel corridore.
- Impostare le variabili di repository FLASHDATA_BIN e FLASHDATA_STATE_DIR ai suoi percorsi assoluti e FLASHDATA_PROFILE al nome del profilo installato.
name: FlashData access check
on: workflow_dispatch
permissions: {}
concurrency:
group: flashdata-research
cancel-in-progress: false
jobs:
verify:
runs-on: [self-hosted, linux, flashdata-research]
timeout-minutes: 5
steps:
- name: Verify the installed profile without a paid query
shell: bash
env:
FLASHDATA_BIN: ${{ vars.FLASHDATA_BIN }}
FLASHDATA_STATE_DIR: ${{ vars.FLASHDATA_STATE_DIR }}
FLASHDATA_PROFILE: ${{ vars.FLASHDATA_PROFILE }}
FLASHDATA_API_KEY: ""
run: |
set -euo pipefail
: "${FLASHDATA_BIN:?Set the absolute CLI path}"
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${FLASHDATA_PROFILE:?Set the installed profile name}"
test -d "$FLASHDATA_STATE_DIR"
"$FLASHDATA_BIN" auth status --profile "$FLASHDATA_PROFILE" \
--state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
jq -e '.ok and .data.accessVerified
and (.data.identity.identity.recurringAllowed == true)
and (.data.identity.permittedSources | index("google_search") != null)'Eseguire il controllo di accesso
Dopo aver salvato il flusso di lavoro sul ramo predefinito del repository, aprire Azioni → FlashData controllo di accesso → Esegui flusso di lavoro. Aspettatevi true e un controllo di successo. L'accesso mancante o il permesso fallisce il lavoro senza presentare una ricerca.
Mantenere lo stato dell'esecuzione attraverso i lavori
Un corridore effimero inizia senza il diario originale. Utilizzare lo stato di applicazione durevole o un corridore persistente per il lavoro ricorrente retribuito. Reinstallare solo la chiave non può identificare la presentazione di un lavoro precedente. Mantenere la directory di stato e le uscite di attività private; non caricarle come artefatti CI.
Ruotare o revocare l'accesso dispiegato
La polizia di Pause. Nella cartella delle attività, punta FLASHDATA_KEY_FILE in una chiave di sostituzione per lo stesso account e le fonti richieste, quindi eseguire i comandi qui sotto. Ripetere il controllo di accesso e deployment-check.sh; aspettatevi cache: true. Rivolgere la vecchia chiave dopo la verifica e mantenere il profilo e la directory di stato.
set -euo pipefail
. ./runtime.sh
: "${FLASHDATA_KEY_FILE:?Point to the mounted replacement key for the same account}"
run_flashdata auth login --replace --api-key-stdin --non-interactive \
< "$FLASHDATA_KEY_FILE"
run_flashdata auth status --json --non-interactiveSmettere di accedere completamente
Utilizzare il programmatore, revocare la connessione chiave o agente nella console, quindi ripetere il controllo di accesso gratuito. Deve fallire. Il logout locale da solo non revoca le credenziali del server; i file già esportati rimangono sul disco.
Controlli di distribuzione che falliscono
| Sintomo | Risolto |
|---|---|
| Comando non trovato / sbagliato CLI versione | Controllare il comando -v flashdata e FLASHDATA_BIN in runtime.sh. Per Docker, ricostruire ed eseguire il controllo --version dell'immagine. |
| Supporto mancante o il permesso negato | Creare le cartelle di stato e di attività sull'host Docker, di proprietà del servizio UID/GID. Mantenere i loro sentieri stabili. |
| replacement_requires_flag | Il profilo ha una chiave salvata diversa. Verificare prima l'accesso esistente; utilizzare la procedura di rotazione per una sostituzione prevista. |
| Non può decifrare l'accesso salvato | Esegui come utente che l'ha fornito, nello stesso ambiente credenzialial-store. Fornire l'accesso su una nuova destinazione invece di copiare un profilo crittografato del computer portatile. |
| Risultato della verifica dei costi false | Ispezionare balance.json e preflight.json. Richiedere un prezzo disponibile, il permesso di origine e abbastanza equilibrio prima di presentare. |
| run_account_mismatch | Controllare l'account selezionato e le origini API. Ripristinare l'accesso originale; non rinominare la corsa per bypassare il recupero. |
| run_id_input_conflict | Ripristinare la richiesta originale dal tentativo request.json. Utilizzare un nuovo run ID solo per un nuovo compito pagato. |
| CI rimane in coda | Controlla che il corridore sia online e abbia ogni etichetta run-on. Questo flusso di lavoro richiede un persistente corridore Linux. |