fn_registry/python/functions/infra/gsc_auth.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
gsc_auth	function	py	infra	1.0.0	impure	def gsc_auth(credentials_path: str = "", subject: str = "") -> object	Autentica contra la Google Search Console API v1 (searchconsole/webmasters) con una cuenta de servicio JSON. Lee el JSON de credentials_path o, si esta vacio, de la env var GSC_SA_JSON; lanza ValueError claro si falta. Usa service_account.Credentials.from_service_account_file con scope https://www.googleapis.com/auth/webmasters.readonly (solo lectura). subject opcional aplica with_subject(subject) para domain-wide delegation (normalmente vacio en GSC). Construye y retorna el objeto service de googleapiclient.discovery.build('searchconsole','v1', cache_discovery=False) listo para consumir por pull_gsc_search_analytics. Requiere google-api-python-client y google-auth.	seo gsc infra google search-console auth service-account				false	error_go_core	os google.oauth2.service_account googleapiclient.discovery	name desc credentials_path ruta al JSON de la service account de GCP. Si esta vacio, se lee de la env var GSC_SA_JSON. Si tampoco existe, se lanza ValueError. El JSON es un secreto: resolver desde pass o una ruta fuera del repo, nunca commitear. name desc subject opcional. Email para domain-wide delegation (impersonation) via with_subject. Normalmente vacio en Search Console, donde la SA se anade directamente como usuario en GSC sin requerir delegation.	object. El service de googleapiclient (googleapiclient.discovery.Resource) para la API 'searchconsole' v1, autenticado con scope webmasters.readonly y cache_discovery=False. Se pasa a funciones consumidoras como pull_gsc_search_analytics.	true	test_build_se_llama_con_searchconsole_v1_y_cache_off test_credentials_se_cargan_con_scope_readonly test_fallback_a_env_var_gsc_sa_json test_subject_aplica_with_subject test_error_cuando_falta_credential	python/functions/infra/gsc_auth_test.py	python/functions/infra/gsc_auth.py

Ejemplo

import sys
sys.path.insert(0, "python/functions")
from infra import gsc_auth

# Opcion A: ruta explicita al JSON de la service account
service = gsc_auth(credentials_path="/home/enmanuel/secrets/gsc-sa.json")

# Opcion B: leer la ruta de la env var GSC_SA_JSON
#   export GSC_SA_JSON=/home/enmanuel/secrets/gsc-sa.json
service = gsc_auth()

# Verificar la autenticacion listando los sitios verificados:
sites = service.sites().list().execute()
print([s["siteUrl"] for s in sites.get("siteEntry", [])])

Cuando usarla

Antes de pull_gsc_search_analytics (o cualquier llamada a la Search Console API): la usas para obtener el objeto service autenticado una sola vez y reutilizarlo en las consultas posteriores (Search Analytics, sitemaps, sites). Es el punto de entrada del capability group seo.

Gotchas

• Impura: lee un JSON del disco y construye un cliente HTTP de Google. No es determinista ni componible en el nucleo puro.
• Dar de alta la SA en Search Console: el email de la service account debe anadirse manualmente como usuario en Search Console > Settings > Users and permissions (rol Restricted/Full). Sin esto la auth funciona pero las consultas devuelven 403 / sitios vacios.
• Habilitar la API: la "Search Console API" debe estar habilitada en el proyecto GCP de la service account (consola de APIs & Services). Si no, el primer .execute() falla con un error de API deshabilitada.
• El JSON de la SA es un secreto: no commitear nunca. Guardarlo en pass o en una ruta fuera del repo y pasar la ruta por credentials_path o la env var GSC_SA_JSON.
• subject casi siempre vacio: domain-wide delegation solo aplica si impersonas a un usuario de un dominio Workspace; en GSC lo normal es anadir la SA directamente como usuario y dejar subject="".
• Dependencias: requiere google-api-python-client y google-auth en el venv. Ya estan en python/pyproject.toml.

Capability growth log

(sin cambios — v1.0.0 inicial)