Documentatie bekijken
Handleidingen
Voer de CLI-taken van uw app of agent uit op Linux of Docker, verifieer dan de toegang en het resultaat van hergebruik na een herstart.
Op deze pagina
1. Kies de runtime
Gebruik een Linux host met Bash en jq, en een eigenaar API sleutel met google_search toestemming. Start de installatie als de OS-gebruiker die de taak zal uitvoeren. Deze privé-taakmap aanmaken voor stappen 1–4; bestandslabels tonen alle submappen.
umask 077
mkdir -p "$HOME/flashdata-tasks/deployment-check"
cd "$HOME/flashdata-tasks/deployment-check"Installeer eerst de oorspronkelijke CLI. Voer commando -v flashdata uit om zijn absolute pad te vinden en stel dan FLASHDATA_BIN in op dat pad in runtime.sh. Stel hier de profielnaam en het statuspad in en sla het bestand op.
# 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"
}Op een Linux Docker host met curl, tar en sha256sum, download de gepinde CLI voor de host CPU. Bewaar image/Dockerfile en image/.dockerignore hieronder, bouw de afbeelding en sla runtime.sh op. De helper draait als je UID/GID en mount de status- en taakmappen in elke nieuwe container.
(
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
}Controleer de geselecteerde runtime
Uitvoeren vanuit de taakmap. run_flashdata is de helper die opgeslagen is in runtime.sh; alle latere commando's gebruiken zijn profiel en status directory. Het negeert FLASHDATA_API_KEY zodat een omgevingssleutel het opgeslagen profiel niet kan vervangen. Verwacht de CLI en jq versies.
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version2. Installeer de eigenaar toegang eenmaal
Als het profiel al toegang heeft tot de eigenaar, sla dan de import over en voer de onderstaande controle uit. Anders, mount een eigenaar-sleutel geheim bestand leesbaar door de service gebruiker en vervang het voorbeeld pad door de locatie. De import leest het via stdin; Docker kopieert het niet naar de afbeelding.
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-interactiveBevestig het account en de toestemming
De check drukt de account ID af, toegestane bronnen en betrouwbaarheidsbescherming, dan true. Bevestig dat het account ID de beoogde eigenaar is voordat u verder gaat. access.json blijft in de taakmap voor inspectie.
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.jsonCredential storage en persistente bestanden
Inspecteer data.credentialProtection in auth status. Linux kan een ontgrendelde Geheime Dienst gebruiken; een hoofdloze host of de container hierboven kan een eigenaar-alleen platte tekstbestand gebruiken. Houd de staat directory privé en persistent. Zorg voor de ingezette gebruiker apart van het gecodeerde profiel van uw laptop.
| Houden | Locatie |
|---|---|
| Identiteiten en run journaal | FLASHDATA_STATE_DIR |
| Invoer, ontvangsten en resultaten | De taakmap; gemonteerd als /work in Docker. |
3. Valideer het verzoek en de kosten
Bewaar request.json naast runtime.sh. De volgende controle valideert terugkerende toegang en het verzoek, leest actuele prijzen en vergelijkt het met het beschikbare saldo. Zij legt geen zoekopdracht voor en reserveert geen kredieten. Ga alleen verder als het filter true afdrukt.
{
"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. Eenmaal uitvoeren en opnieuw controleren
Bewaar deployment-check.sh hieronder. Met een nieuwe deployment-first-task run ID, de eerste uitvoering dient een betaalde zoekopdracht; de tweede start een nieuw proces en leest het opgeslagen resultaat. Als deze ID al in hetzelfde profiel is voltooid, proberen beide deze te hergebruiken.
deployment-check.sh opslaan
Maak deployment-check.sh naast runtime.sh en request.json in de privé-taakmap op de host. Kopieer het volledige script hieronder en sla het op.
#!/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"De opgeslagen controle tweemaal uitvoeren
Uitvoeren van die host taakmap als dezelfde service gebruiker. Beide processen laden de runtime.sh opgeslagen in stap 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.shControleer het tweede ontvangstbewijs
Voor een nieuwe run, verwacht cached: false, dan cached: true. Elke poging print zijn deployment-check.XXXXXX map en slaat request.json, receipt.json en error.json, plus result.json op succes. De cached bon meldt het oorspronkelijke gebruik. Een mislukte poging houdt zijn bestanden voor herstel.
{
"ok": true,
"runId": "deployment-first-task",
"cached": true
}Lees het opgeslagen zoekresultaat
Stel ATTEMPT_DIR in op de tweede succesvolle map hierboven afgedrukt, bijvoorbeeld export ATTEMPT_DIR= './deployment-check.ABC123'. Deze commando's lezen alleen lokale bestanden.
# 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"Verplaatsen van een implementatiecontrole naar een terugkerende taak
Deze check heeft een vaste ID. Voor terugkerende werkzaamheden, geef elke beoogde gebeurtenis zijn eigen ID en behoud de geselecteerde runtime, account, invoer snapshots en status mounts. Pas het query commando van de terugkerende runner aan om run_flashdata te gebruiken, zodat Docker taken in de container blijven.
Toegang controleren vanuit GitHub-acties
Gebruik een vertrouwde, aanhoudende Linux-runner met Bash, jq en het CLI-profiel dat al is geïnstalleerd onder de OS-gebruiker van de runner. Sla deze workflow op in de repository van je applicatie. Het controleert de host CLI zonder een betaalde taak uit te voeren.
- Geef het flashdata-onderzoekslabel aan die loper.
- Stel repository-variabelen FLASHDATA_BIN en FLASHDATA_STATE_DIR in op zijn absolute paden, en FLASHDATA_PROFILE op de geïnstalleerde profielnaam.
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)'Toegangscontrole uitvoeren
Na het opslaan van de workflow op de standaard branch van de repository, open Acties → FlashData toegangscontrole → Werkstroom uitvoeren. Verwacht true en een succesvolle controle. Ontbrekende toegang of toestemming mislukt de taak zonder een zoekopdracht in te dienen.
Houd de uitvoeringsstaat over banen heen
Een kortstondige loper begint zonder het originele dagboek. Gebruik duurzame applicatiestatus of een aanhoudende runner voor betaalde terugkerende werk. Het opnieuw installeren van alleen de sleutel kan de inzending van een vorige taak niet identificeren. Houd de status directory en taakuitvoer privé; upload ze niet als CI artefacten.
Uitgevoerde toegang draaien of intrekken
Pauzeer de centrale. In de taakmap, punt FLASHDATA_KEY_FILE op een vervangende sleutel voor dezelfde account en vereiste bronnen, voer dan de onderstaande commando's uit. Herhaal de toegangscontrole en deployment-check.sh; verwacht cached: true. Herroep de oude sleutel na verificatie en houd het profiel en de status directory.
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-interactiveToegang volledig stoppen
Pauzeer de scheduler, trek de sleutel of agent verbinding in de console in en herhaal dan de vrije toegangscontrole. Het moet mislukken. Lokale logout alleen herroept de server credential niet; reeds geëxporteerde bestanden blijven op schijf.
Inzetcontroles die falen
| Symptoom | Repareren |
|---|---|
| Opdracht niet gevonden / verkeerde CLI versie | Controleer commando -v flashdata en FLASHDATA_BIN in runtime.sh. Voor Docker, herbouw en voer de --version-controle van de afbeelding uit. |
| Ontbrekende aankoppel- of machtiging geweigerd | Maak de status- en taakmappen op de Docker-host, eigendom van de service UID/GID. Hou hun paden stabiel. |
| replacement_requires_flag | Het profiel heeft een andere opgeslagen sleutel. Controleer de bestaande toegang eerst; gebruik de rotatieprocedure voor een voorgenomen vervanging. |
| Kan opgeslagen toegang niet decoderen | Uitvoeren als de gebruiker die het provisioned, in dezelfde credential-store omgeving. Toegang tot een nieuwe bestemming in plaats van een gecodeerd laptopprofiel te kopiëren. |
| Kostencontrole geeft false terug | Inspecteer balance.json en preflight.json. Vereist een beschikbare prijs, bron toestemming en voldoende evenwicht voordat u het indienen. |
| run_account_mismatch | Controleer de geselecteerde account en API origins. Herstel de oorspronkelijke toegang; hernoem de run niet om herstel te omzeilen. |
| run_id_input_conflict | Herstel het oorspronkelijke verzoek van de poging request.json. Gebruik een nieuwe run ID alleen voor een voorgenomen nieuwe betaalde taak. |
| CI blijft in de wachtrij | Controleer of de loper online is en elk label heeft. Deze workflow vereist een hardnekkige Linux-runner. |