Parcourir la documentation
Guides
Exécutez les tâches CLI de votre application ou de votre agent sous Linux ou Docker, puis vérifiez l’accès et la réutilisation des résultats après un redémarrage.
Sur cette page
1. Choisir l’environnement d’exécution
Utilisez un hôte Linux avec Bash et jq, ainsi qu’une clé API propriétaire disposant de la permission google_search. Effectuez la configuration avec l’utilisateur du système qui exécutera la tâche. Créez ce dossier privé pour les étapes 1 à 4 ; les noms de fichiers indiquent les éventuels sous-dossiers.
umask 077
mkdir -p "$HOME/flashdata-tasks/deployment-check"
cd "$HOME/flashdata-tasks/deployment-check"Installez d’abord la CLI native. Exécutez command -v flashdata pour trouver son chemin absolu, puis affectez ce chemin à FLASHDATA_BIN dans runtime.sh. Définissez ici le nom du profil et le chemin de l’état persistant, puis enregistrez le fichier.
# 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"
}Sur un hôte Docker Linux équipé de curl, tar et sha256sum, téléchargez la version fixée de la CLI pour l’architecture du processeur hôte. Enregistrez image/Dockerfile et image/.dockerignore ci-dessous, construisez l’image, puis enregistrez runtime.sh. La fonction utilise vos UID/GID et monte les dossiers d’état et de tâche dans chaque nouveau conteneur.
(
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
}Vérifier l’environnement choisi
Lancez la commande depuis le dossier de tâche. run_flashdata est la fonction enregistrée dans runtime.sh ; toutes les commandes suivantes utilisent son profil et son répertoire d’état. Elle ignore FLASHDATA_API_KEY pour qu’une clé d’environnement ne remplace pas le profil enregistré. Les versions de la CLI et de jq doivent s’afficher.
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version2. Configurer l’accès propriétaire une seule fois
Si le profil dispose déjà d’un accès propriétaire, passez l’importation et lancez la vérification ci-dessous. Sinon, montez un fichier secret contenant la clé propriétaire, lisible par l’utilisateur du service, et remplacez le chemin d’exemple par son emplacement. L’importation le lit via stdin ; Docker ne le copie pas dans l’image.
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-interactiveConfirmer le compte et la permission
La vérification affiche l’identifiant du compte, les sources autorisées et la protection des identifiants, puis true. Confirmez que l’identifiant correspond au compte propriétaire prévu avant de continuer. access.json reste dans le dossier de tâche pour vérification.
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.jsonStockage des identifiants et fichiers persistants
Examinez data.credentialProtection dans auth status. Linux peut utiliser un service Secret Service déverrouillé ; un hôte sans interface graphique ou le conteneur ci-dessus peut utiliser un fichier en clair lisible uniquement par son propriétaire. Gardez le répertoire d’état privé et persistant. Configurez l’accès de l’utilisateur déployé séparément du profil chiffré de votre ordinateur portable.
| À conserver | Emplacement |
|---|---|
| Identifiants et journal d’exécution | FLASHDATA_STATE_DIR |
| Paramètres, reçus et résultats | Le dossier de tâche, monté sous /work dans Docker. |
3. Valider la requête et le coût
Enregistrez request.json à côté de runtime.sh. La vérification suivante valide l’accès récurrent et la requête, lit les tarifs actuels et les compare au solde disponible. Elle ne soumet aucune recherche et ne réserve pas de crédits. Continuez uniquement lorsque le filtre affiche 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. Exécuter une fois et vérifier la réutilisation
Enregistrez deployment-check.sh ci-dessous. Avec un nouvel identifiant d’exécution deployment-first-task, la première exécution soumet une recherche payante ; la seconde démarre un nouveau processus et lit le résultat enregistré. Si cet identifiant correspond déjà à une exécution terminée dans le même profil, les deux tentatives la réutilisent.
Enregistrer deployment-check.sh
Créez deployment-check.sh à côté de runtime.sh et request.json, dans le dossier privé de tâche sur l’hôte. Copiez-y le script complet ci-dessous et enregistrez-le.
#!/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"Lancer deux fois la vérification enregistrée
Lancez les commandes depuis ce dossier de l’hôte avec le même utilisateur de service. Les deux processus chargent runtime.sh enregistré à l’étape 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.shVérifier le second reçu
Pour une nouvelle exécution, le résultat attendu indique cached: false, puis cached: true. Chaque tentative affiche son dossier deployment-check.XXXXXX et enregistre request.json, receipt.json et error.json, ainsi que result.json en cas de réussite. Le reçu mis en cache indique la consommation d’origine. Une tentative en échec conserve ses fichiers pour la reprise.
{
"ok": true,
"runId": "deployment-first-task",
"cached": true
}Lire le résultat de recherche enregistré
Définissez ATTEMPT_DIR avec le second dossier réussi affiché ci-dessus, par exemple export ATTEMPT_DIR='./deployment-check.ABC123'. Ces commandes lisent uniquement des fichiers locaux.
# 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"Passer de la vérification de déploiement à une tâche récurrente
Cette vérification utilise un identifiant d’exécution fixe. Pour des tâches récurrentes, donnez à chaque occurrence prévue son propre identifiant et conservez l’environnement choisi, le compte, les instantanés d’entrée et les montages d’état. Adaptez la commande de requête du script récurrent pour utiliser run_flashdata afin que les tâches Docker restent dans le conteneur.
Vérifier l’accès depuis GitHub Actions
Utilisez un runner Linux de confiance et persistant, avec Bash, jq et le profil CLI déjà installé pour l’utilisateur du système qui l’exécute. Enregistrez ce workflow dans le dépôt de votre application. Il vérifie la CLI de l’hôte sans lancer de tâche payante.
- Attribuez le label flashdata-research à ce runner.
- Définissez les variables du dépôt FLASHDATA_BIN et FLASHDATA_STATE_DIR avec les chemins absolus correspondants, et FLASHDATA_PROFILE avec le nom du profil installé.
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)'Lancer la vérification d’accès
Après avoir enregistré le workflow sur la branche par défaut du dépôt, ouvrez Actions → FlashData access check → Run workflow. Le résultat attendu est true et une vérification réussie. Un accès ou une permission manquants font échouer le job sans soumettre de recherche.
Conserver l’état d’exécution entre les jobs
Un runner éphémère démarre sans le journal d’origine. Utilisez un état applicatif durable ou un runner persistant pour les tâches récurrentes payantes. Réinstaller uniquement la clé ne permet pas d’identifier la soumission d’un job précédent. Gardez le répertoire d’état et les sorties de tâche privés ; ne les publiez pas comme artefacts CI.
Remplacer ou révoquer l’accès déployé
Suspendez l’envoi de nouvelles tâches. Dans le dossier de tâche, faites pointer FLASHDATA_KEY_FILE vers une clé de remplacement pour le même compte et les sources requises, puis lancez les commandes ci-dessous. Répétez la vérification d’accès et deployment-check.sh ; le résultat attendu indique cached: true. Révoquez l’ancienne clé après vérification et conservez le profil et le répertoire d’état.
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-interactiveArrêter complètement l’accès
Mettez le planificateur en pause, révoquez la clé ou la connexion de l’agent dans la console, puis répétez la vérification gratuite de l’accès. Elle doit échouer. Une déconnexion locale ne révoque pas à elle seule l’identifiant côté serveur ; les fichiers déjà exportés restent sur disque.
Résoudre les échecs de vérification du déploiement
| Symptôme | Correction |
|---|---|
| Commande introuvable / mauvaise version de CLI | Vérifiez command -v flashdata et FLASHDATA_BIN dans runtime.sh. Pour Docker, reconstruisez l’image et lancez sa vérification --version. |
| Montage manquant ou permission refusée | Créez les dossiers d’état et de tâche sur l’hôte Docker avec les UID/GID du service comme propriétaires. Conservez des chemins stables. |
| replacement_requires_flag | Le profil contient une autre clé enregistrée. Vérifiez d’abord l’accès existant ; utilisez la procédure de rotation pour un remplacement voulu. |
| Impossible de déchiffrer l’accès enregistré | Exécutez avec l’utilisateur qui a configuré l’accès, dans le même environnement de stockage d’identifiants. Configurez l’accès sur la nouvelle destination plutôt que de copier un profil chiffré depuis un ordinateur portable. |
| La vérification de coût renvoie false | Examinez balance.json et preflight.json. Exigez un tarif disponible, la permission de la source et un solde suffisant avant de soumettre. |
| run_account_mismatch | Vérifiez le compte sélectionné et les origines API. Rétablissez l’accès d’origine ; ne renommez pas l’exécution pour contourner la reprise. |
| run_id_input_conflict | Restaurez la requête d’origine depuis request.json de la tentative. Utilisez un nouvel identifiant d’exécution uniquement pour une nouvelle tâche payante voulue. |
| Le job CI reste en file d’attente | Vérifiez que le runner est en ligne et possède tous les labels runs-on. Ce workflow nécessite un runner Linux auto-hébergé persistant. |