Explorar documentación
Guías
Ejecuta las tareas de CLI de tu aplicación o agente en Linux o Docker. Después, comprueba que el acceso y los resultados se puedan reutilizar tras un reinicio.
En esta página
1. Elige el tiempo de ejecución
Utilice un host Linux con Bash y jq, y una tecla API propietario con permiso google_search. Ejecute la configuración como el usuario OS que ejecutará la tarea. Cree esta carpeta de tarea privada para los pasos 1–4; etiquetas de archivos muestren cualquier subcarpete.
umask 077
mkdir -p "$HOME/flashdata-tasks/deployment-check"
cd "$HOME/flashdata-tasks/deployment-check"Instala el nativo CLI primero. Correr comando -v flashdata para encontrar su camino absoluto, luego establecer FLASHDATA_BIN a esa ruta en runtime.sh. Establecer el nombre de perfil y la ruta de estado persistente una vez aquí, a continuación, guardar el archivo.
# 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"
}En una Linux Docker host con curl, tar y sha256sum, descargar el pinned CLI para el host CPU. Guardar imagen/Dockerfile imagen y imagen/.dockerignore abajo, construir la imagen, luego guardar runtime.sh. El ayudante funciona como su UID/GID y monta las carpetas de estado y tarea en cada nuevo contenedor.
(
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
}Compruebe el tiempo de ejecución seleccionado
run_flashdata es el ayudante guardado en runtime.sh; todos los comandos posteriores utilizan su perfil y directorio estatal. Ignora FLASHDATA_API_KEY por lo que una clave ambiental no puede reemplazar el perfil guardado. Espere las versiones CLI y jq.
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version2. Instalar el acceso del propietario una vez
Si el perfil ya tiene acceso al propietario, salta la importación y ejecute el cheque a continuación. De lo contrario, monta un archivo secreto propietario-key legible por el usuario del servicio y reemplaza la ruta del ejemplo con su ubicación. La importación lo lee a través de stdin; Docker no lo copia en la imagen.
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-interactiveConfirme la cuenta y el permiso
El cheque imprime la cuenta ID, las fuentes permitidas y la protección credencial, entonces es cierto. Confirme la cuenta ID es el propietario indicado antes de continuar. access.json se queda en la carpeta de tareas para la inspección.
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.jsonAlmacenamiento creíble y archivos persistentes
Inspeccione data.credentialProtection en estado de austeridad. Linux puede utilizar un servicio secreto desbloqueado; un host sin cabeza o el contenedor anterior puede utilizar un archivo de texto solo propietario. Mantenga el directorio estatal privado y persistente. Proporcione al usuario desplegado separadamente del perfil cifrado de su computadora portátil.
| Mantente quieto. | Ubicación |
|---|---|
| Credenciales y diario de ejecución | FLASHDATA_STATE_DIR |
| Entrada, recibos y resultados | La carpeta de tarea; montada como /work en Docker. |
3. Validar la solicitud y el costo
Guardar request.json junto a runtime.sh. El siguiente cheque valida el acceso recurrente y la solicitud, lee los precios actuales y lo compara con el saldo disponible. No presenta ninguna búsqueda y no reserva créditos. Continúe sólo cuando el filtro imprima verdad.
{
"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. Correr una vez y verificar la reutilización
Guardar deployment-check.sh a continuación. Con un nuevo ID de la primera ejecución, la primera ejecución presenta una búsqueda pagada; el segundo comienza un nuevo proceso y lee el resultado guardado. Si este ID ya se ha completado en el mismo perfil, ambos intentos reutilizarlo.
Guardar deployment-check.sh
Cree deployment-check.sh junto a runtime.sh y request.json en la carpeta de tareas privada en el host. Copia el script completo a continuación y guárdalo.
#!/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"Corre el cheque guardado dos veces
Ejecutar desde esa carpeta de tareas de host como el mismo usuario de servicio. Ambos procesos cargan el runtime.sh guardado en el paso 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.shVerificar el segundo recibo
Para una nueva ejecución, espere caché: falso, luego caché: cierto. Cada intento imprime su carpeta deployment-check.XXXXXX y guarda request.json, receipt.json y error.json, más result.json sobre el éxito. La recepción caché informa el uso original. Un intento fallido mantiene sus archivos para la recuperación.
{
"ok": true,
"runId": "deployment-first-task",
"cached": true
}Lea el resultado de la búsqueda guardada
Establecer ATTEMPT_DIR a la segunda carpeta exitosa impresa anteriormente, por ejemplo exportar ATTEMPT_DIR='./deployment-check.ABC123'. Estos comandos leen solamente los archivos locales.
# 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"Mover de un cheque de implementación a una tarea recurrente
Este cheque tiene una ejecución fija ID. Para el trabajo recurrente, da a cada ocurrencia prevista su propio ID y retiene el tiempo de ejecución seleccionado, cuenta, instantáneas de entrada y montajes estatales. Adapte el comando de consulta del corredor recurrente para utilizar run_flashdata así que las tareas Docker permanecen dentro del contenedor.
Compruebe el acceso desde GitHub Actions
Utilice un controlador Linux confiable y persistente con Bash, jq y el perfil CLI ya instalado bajo el usuario OS del corredor. Ahorre este flujo de trabajo en el repositorio de su aplicación. Chequea el host CLI sin ejecutar una tarea pagada.
- Asignar la etiqueta de flashdata-research a ese corredor.
- Establecer variables de repositorio FLASHDATA_BIN y FLASHDATA_STATE_DIR a sus caminos absolutos, y FLASHDATA_PROFILE al nombre de perfil instalado.
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)'Ejecute el cheque de acceso
Después de guardar el flujo de trabajo en la rama predeterminada del repositorio, abra Acciones → FlashData check → Ejecute el flujo de trabajo. Espere verdadero y un cheque exitoso. Falta el acceso o permiso falla el trabajo sin enviar una búsqueda.
Mantener el estado de ejecución en puestos de trabajo
Un corredor efímero comienza sin la revista original. Use el estado de aplicación durable o un corredor persistente para el trabajo recurrente pagado. Reinstalar sólo la clave no puede identificar la presentación de un trabajo anterior. Mantenga el directorio estatal y salidas de tareas privadas; no subirlos como artefactos CI.
Rotar o revocar el acceso desplegado
Despacho de pausa. En la carpeta de tarea, puntee FLASHDATA_KEY_FILE en una llave de reemplazo para la misma cuenta y fuentes requeridas, luego ejecute los comandos a continuación. Repita el cheque de acceso y deployment-check.sh; espere caché: verdadero. Revuelva la llave antigua después de la verificación y mantenga el directorio de perfil y estado.
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-interactiveParar el acceso completamente
Pausa el cronogramador, revoca la conexión de clave o agente en la consola, luego repite el cheque de acceso gratuito. Debe fallar. El logo local por sí solo no revoca el servidor credencial; los archivos ya exportados permanecen en disco.
Controles de despliegue que fallan
| Síntoma | Arreglos |
|---|---|
| Comando no encontrado / incorrecta CLI versión | Comprueba el comando -v flashdata y FLASHDATA_BIN en runtime.sh. Para Docker, reconstruye y ejecuta el cheque --version de la imagen. |
| Falta de montaje o permiso denegado | Cree las carpetas de estado y tarea en el host Docker, propiedad del servicio UID/GID. Mantenga sus caminos estables. |
| replacement_requires_flag | El perfil tiene una clave diferente guardada. Verifique primero el acceso existente; utilice el procedimiento de rotación para un reemplazo previsto. |
| No puede descifrar el acceso guardado | Ejecutar como el usuario que lo proporcionó, en el mismo entorno de plantación credencial. Facilitar el acceso a un nuevo destino en lugar de copiar un perfil portátil cifrado. |
| Cost check devuelve false | Inspeccione balance.json y preflight.json. Requiere un precio disponible, permiso de origen y suficiente equilibrio antes de enviar. |
| run_account_mismatch | Compruebe la cuenta seleccionada y los orígenes de API. Restaurar el acceso original; no vuelva a llamar la carrera a la recuperación de bypass. |
| run_id_input_conflict | Restaurar la solicitud original del request.json del intento. Utilice un nuevo ID sólo para una nueva tarea pagada. |
| CI se queda apagado | Compruebe que el corredor está en línea y tiene cada etiqueta de carreras. Este flujo de trabajo requiere un corredor Linux persistente. |