upd

2026-06-15 15:36:52 +02:00
parent 54247186cf
commit d648589ac7
3 changed files with 896 additions and 19 deletions
@@ -12,6 +12,8 @@ Discovery endpointy slouzi k dohledani dostupnych resource, metod, schema a OAut
 ## OAuth

 - `POST /google/oauth/token` podporuje `authorization_code` a `refresh_token` grant.
+- `GET /google/oauth/scopes` vraci doporucene scopes pro podporovane sluzby.
+- `GET /google/oauth/authorize-url` vygeneruje Google consent URL.
 - `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.
@@ -24,6 +26,61 @@ OAuth client a service account hodnoty je vhodne predavat pres environment varia
 - `GOOGLE_PRIVATE_KEY`
 - `GOOGLE_SCOPES`

+### Env promenne a request alternativy
+
+Swagger obsahuje `GET /google/configuration`, ktery vypise podporovane env promenne, jejich pouziti a alternativy v requestu. Endpoint nevraci hodnoty secrets.
+
+- `GOOGLE_CLIENT_ID`: `clientId`, `X-Google-Client-Id`
+- `GOOGLE_CLIENT_SECRET`: `clientSecret`, `X-Google-Client-Secret`
+- `GOOGLE_REDIRECT_URI`: `redirectUri`, `X-Google-Redirect-Uri`
+- `GOOGLE_SERVICE_ACCOUNT_EMAIL`: `serviceAccountEmail`, `X-Google-Service-Account-Email`
+- `GOOGLE_PRIVATE_KEY`: `privateKey`, `X-Google-Private-Key`
+- `GOOGLE_SCOPES`: `scope`, `scopes`, `X-Google-Scopes`
+- `GOOGLE_ACCESS_TOKEN`: `Authorization: Bearer <token>`, `accessToken`, `accessTokenEnv`, `X-Google-Access-Token`, `X-Google-Access-Token-Env`
+- `GOOGLE_API_KEY`: `apiKey`, `apiKeyEnv`, `X-Google-Api-Key`, `X-Google-Api-Key-Env`
+
+### OAuth krok za krokem
+
+1. Zavolej `GET /google/oauth/scopes`.
+2. Vyber scopes, napr. Sheets + Drive metadata:
+
+```text
+https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.metadata.readonly
+```
+
+3. Zavolej:
+
+```text
+GET /google/oauth/authorize-url?redirectUri=https://example.test/oauth/callback&scopes=https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.metadata.readonly
+```
+
+4. Otevri `authorizationUrl` z odpovedi.
+5. Po souhlasu Google presmeruje na `redirectUri` s query parametrem `code`.
+6. Code vymen:
+
+```json
+{
+  "grantType": "authorization_code",
+  "code": "code-from-google-redirect",
+  "redirectUri": "https://example.test/oauth/callback"
+}
+```
+
+7. `access_token` posilej do produktovych endpointu jako:
+
+```text
+Authorization: Bearer <access_token>
+```
+
+Pro dlouhodobe pouziti si uloz `refresh_token` mimo zdrojovy kod a obnovuj token pres:
+
+```json
+{
+  "grantType": "refresh_token",
+  "refreshToken": "stored-refresh-token"
+}
+```
+
 ## 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.
@@ -64,8 +121,11 @@ Krome obecne proxy jsou dostupne konkretni wrappery nad nejbeznejsimi Google API

 ### Sheets

+- `GET /google/sheets/spreadsheets` - seznam Google Sheets souboru; `spreadsheetId` je `files[].id`
 - `POST /google/sheets/spreadsheets`
 - `GET /google/sheets/spreadsheets/{spreadsheetId}`
+- `GET /google/sheets/spreadsheets/{spreadsheetId}/sheets` - seznam tabu/listu; numericke `sheetId` je `sheets[].properties.sheetId`, A1 range pouziva `sheets[].properties.title`
+- `POST /google/sheets/write-by-url` - zapis hodnot podle plne URL spreadsheetu a nazvu listu
 - `POST /google/sheets/spreadsheets/{spreadsheetId}/batch-update`
 - `GET /google/sheets/spreadsheets/{spreadsheetId}/values?range=Sheet1!A1:B10`
 - `PUT /google/sheets/spreadsheets/{spreadsheetId}/values?range=Sheet1!A1`
@@ -73,6 +133,31 @@ Krome obecne proxy jsou dostupne konkretni wrappery nad nejbeznejsimi Google API
 - `POST /google/sheets/spreadsheets/{spreadsheetId}/values/batch-update`
 - `POST /google/sheets/spreadsheets/{spreadsheetId}/values/batch-clear`

+#### Zapis podle URL a nazvu listu
+
+Endpoint `POST /google/sheets/write-by-url` je urceny pro bezny zapis bez rucni prace se `spreadsheetId` a A1 range.
+
+```json
+{
+  "spreadsheetUrl": "https://docs.google.com/spreadsheets/d/1abcDEFghiJKLmnopQRstuVWXyz/edit#gid=0",
+  "sheetName": "Objednavky",
+  "startCell": "A1",
+  "mode": "append",
+  "valueInputOption": "USER_ENTERED",
+  "values": [
+    ["Datum", "Zakaznik", "Castka"],
+    ["2026-06-15", "ACME", 1234]
+  ]
+}
+```
+
+Chovani:
+
+- `mode=append` vola Google Sheets append a prida radky pod existujici tabulku.
+- `mode=update` vola Google Sheets update a prepise bunky od `startCell`.
+- `sheetName` muze obsahovat mezery i apostrofy; sluzba ho sama escapuje do A1 range.
+- `spreadsheetUrl` muze byt bezna URL ve tvaru `https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit#gid=0`.
+
 ### Drive

 - `GET /google/drive/files`
@@ -121,6 +206,18 @@ Krome obecne proxy jsou dostupne konkretni wrappery nad nejbeznejsimi Google API
 - `PATCH /google/tasks/lists/{tasklistId}/tasks/{taskId}`
 - `DELETE /google/tasks/lists/{tasklistId}/tasks/{taskId}`

+## Kde vzit ID
+
+- `calendarId`: `GET /google/calendar/calendars`, hlavni kalendar lze typicky volat jako `primary`.
+- `eventId`: `GET /google/calendar/calendars/{calendarId}/events`.
+- `spreadsheetId`: `GET /google/sheets/spreadsheets`, pole `files[].id`.
+- `sheetId`: `GET /google/sheets/spreadsheets/{spreadsheetId}/sheets`, pole `sheets[].properties.sheetId`.
+- `fileId`: `GET /google/drive/files`, pole `files[].id`.
+- `messageId`: `GET /google/gmail/messages`, pole `messages[].id`.
+- `documentId`: ID Google Docs souboru z Drive.
+- `presentationId`: ID Google Slides souboru z Drive.
+- `formId`: ID Google Forms souboru z Drive nebo odpoved z `POST /google/forms/forms`.
+
 ## AppFactory overeni

 Po deploy over: