initial ai

2026-06-15 15:12:15 +02:00
parent 3b0a61fd5a
commit a882456466
4 changed files with 1646 additions and 18 deletions
@@ -0,0 +1,55 @@
+# Google API communication
+
+Sluzba poskytuje obecnou komunikacni vrstvu pro Google API. Neobsahuje secrets ve zdrojovem kodu a pro verejne routovani pouziva `ROOT_PATH`, aby Swagger/OpenAPI fungoval za AppFactory prefixem `/apps/<app-id>`.
+
+## Discovery
+
+- `GET /google/discovery/apis` vraci seznam Google API dostupnych pres Google Discovery service.
+- `GET /google/discovery/apis/{api}/{version}/rest` vraci REST discovery dokument konkretniho API, napr. `drive/v3`.
+
+Discovery endpointy slouzi k dohledani dostupnych resource, metod, schema a OAuth scope pro konkretni Google API.
+
+## OAuth
+
+- `POST /google/oauth/token` podporuje `authorization_code` a `refresh_token` grant.
+- `POST /google/oauth/service-account-token` podporuje service account JWT bearer flow.
+- `POST /google/oauth/revoke` revokuje token.
+- `GET /google/oauth/tokeninfo` vraci informace o access tokenu nebo ID tokenu.
+
+OAuth client a service account hodnoty je vhodne predavat pres environment variables:
+
+- `GOOGLE_CLIENT_ID`
+- `GOOGLE_CLIENT_SECRET`
+- `GOOGLE_SERVICE_ACCOUNT_EMAIL`
+- `GOOGLE_PRIVATE_KEY`
+- `GOOGLE_SCOPES`
+
+## Obecne REST volani
+
+`POST /google/request` je genericka proxy pro Google REST API. Request obsahuje HTTP metodu, cilovou Google URL nebo kombinaci `baseUrl` a `path`, volitelne query parametry, body a autorizaci.
+
+Priklad volani Google Drive:
+
+```json
+{
+  "method": "GET",
+  "baseUrl": "https://www.googleapis.com",
+  "path": "/drive/v3/files",
+  "query": {
+    "pageSize": 10
+  },
+  "accessTokenEnv": "GOOGLE_ACCESS_TOKEN"
+}
+```
+
+Z bezpecnostnich duvodu jsou povolene jen HTTPS URL na Google domenach. Requesty na jine hosty sluzba odmita.
+
+## AppFactory overeni
+
+Po deploy over:
+
+- `GET /apps/google-service/health`
+- `GET /apps/google-service/docs`
+- `GET /apps/google-service/openapi.json`
+
+OpenAPI dokument musi obsahovat `servers[0].url` s hodnotou `ROOT_PATH`, napr. `/apps/google-service`, aby Swagger UI volalo endpointy pres verejnou proxy cestu.