appfactory/google-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
google-service/README.md
T
JiriUhlir 8f7f8404c3 upt
2026-06-15 16:00:12 +02:00

200 lines
6.7 KiB
Markdown
Raw Permalink Blame History

# google-service
Node.js TypeScript sluzba pro komunikaci s Google API za AppFactory reverse proxy.
## Endpointy
- `GET /`
- `GET /health`
- `GET /docs`
- `GET /openapi.json`
- `GET /google/discovery/apis`
- `GET /google/discovery/apis/{api}/{version}/rest`
- `POST /google/oauth/token`
- `GET /google/oauth/scopes`
- `GET /google/oauth/authorize-url`
- `POST /google/oauth/service-account-token`
- `POST /google/oauth/revoke`
- `GET /google/oauth/tokeninfo`
- `GET|POST|PATCH|DELETE /google/calendar/...`
- `GET|POST|PUT /google/sheets/...`
- `POST /google/sheets/write-by-url`
- `GET|POST|PATCH|DELETE /google/drive/...`
- `GET|POST /google/gmail/...`
- `GET|POST /google/docs/...`
- `GET|POST /google/slides/...`
- `GET|POST /google/forms/...`
- `GET|POST|PATCH|DELETE /google/people/...`
- `GET|POST|PATCH|DELETE /google/tasks/...`
- `POST /google/request`
## Konfigurace
Volitelne environment variables:
- `ROOT_PATH` - verejny prefix za AppFactory proxy, napr. `/apps/google-service`
- `PORT` - port aplikace, vychozi hodnota je `3000`
- `GOOGLE_CLIENT_ID` a `GOOGLE_CLIENT_SECRET` - OAuth client pro authorization code a refresh token flow
- `GOOGLE_SERVICE_ACCOUNT_EMAIL`, `GOOGLE_PRIVATE_KEY`, `GOOGLE_SCOPES` - service account JWT flow
- `GOOGLE_API_KEY` - API key pro Google API, ktere ji podporuji
Secrets se nevraci v zadnem endpointu a neloguji se.
## Credentials ve Swaggeru
`GET /google/configuration` vraci prehled podporovanych env promennych a jejich request alternativ. Nevraci hodnoty secrets.
Env promenne lze nahradit primo v requestu:
- `GOOGLE_CLIENT_ID`: `clientId` nebo `X-Google-Client-Id`
- `GOOGLE_CLIENT_SECRET`: `clientSecret` nebo `X-Google-Client-Secret`
- `GOOGLE_REDIRECT_URI`: `redirectUri` nebo `X-Google-Redirect-Uri`
- `GOOGLE_SERVICE_ACCOUNT_EMAIL`: `serviceAccountEmail` nebo `X-Google-Service-Account-Email`
- `GOOGLE_PRIVATE_KEY`: `privateKey` nebo `X-Google-Private-Key`
- `GOOGLE_SCOPES`: `scope`, `scopes` nebo `X-Google-Scopes`
- `GOOGLE_SERVICE_ACCOUNT_JSON`: `serviceAccountJson`, `serviceAccountJsonEnv`, `X-Google-Service-Account-Json`, `X-Google-Service-Account-Json-Env`
- `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`
## Obecne volani Google API
`POST /google/request` umi volat libovolny HTTPS endpoint na Google domene. Autorizace muze jit pres:
- `Authorization: Bearer <token>` header na requestu do sluzby
- `X-Google-Access-Token` header
- `X-Google-Access-Token-Env` header, napr. `GOOGLE_ACCESS_TOKEN`
- `X-Google-Api-Key` nebo `X-Google-Api-Key-Env` header
- `accessToken` v body
- `accessTokenEnv` v body, napr. `GOOGLE_ACCESS_TOKEN`
- `GOOGLE_API_KEY`, `apiKey` nebo `apiKeyEnv` pro endpointy podporujici API key
Priklad:
```json
{
"method": "GET",
"baseUrl": "https://www.googleapis.com",
"path": "/drive/v3/files",
"query": {
"pageSize": 10
},
"accessTokenEnv": "GOOGLE_ACCESS_TOKEN"
}
```
## Konkretni Google API wrappery
Sluzba ma konkretni endpointy pro bezne Google produkty, aby klient nemusel skladat cilove Google URL sam:
- Calendar: kalendare, eventy, presun eventu
- Sheets: spreadsheet metadata, batch update, cteni hodnot, update hodnot, append, batch clear
- Drive: soubory, export, opravneni
- Gmail: profil, zpravy, odeslani zpravy, labels
- Docs: vytvoreni dokumentu, nacteni dokumentu, batch update
- Slides: vytvoreni prezentace, nacteni prezentace, batch update
- Forms: vytvoreni formulare, nacteni formulare, batch update, responses
- People: connections, kontakt, vytvoreni/uprava/smazani kontaktu
- Tasks: task lists, tasky, uprava/smazani tasku
Autorizace je stejna jako u obecne proxy: `Authorization: Bearer <token>`, pripadne `accessToken`, `accessTokenEnv`, `apiKey` nebo `apiKeyEnv` v JSON body.
Priklad vytvoreni udalosti:
```json
POST /google/calendar/calendars/primary/events
{
"summary": "Schuzka",
"start": {
"dateTime": "2026-06-15T10:00:00+02:00"
},
"end": {
"dateTime": "2026-06-15T11:00:00+02:00"
}
}
```
Priklad append do Google Sheets:
```json
POST /google/sheets/spreadsheets/{spreadsheetId}/values/append?range=Sheet1!A1
{
"majorDimension": "ROWS",
"values": [
["A", "B", "C"]
]
}
```
Priklad zapisu do Google Sheets podle URL a nazvu listu:
```json
POST /google/sheets/write-by-url
{
"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]
]
}
```
`mode=append` prida radky pod existujici data. `mode=update` prepise bunky od `startCell`.
Stejny endpoint lze volat primo se service account JSON. V tom pripade se neposila `Authorization` header; sluzba si z `client_email` a `private_key` sama vystavi access token:
```json
{
"spreadsheetUrl": "https://docs.google.com/spreadsheets/d/1abcDEFghiJKLmnopQRstuVWXyz/edit#gid=0",
"sheetName": "Objednavky",
"mode": "append",
"values": [
["2026-06-15", "ACME", 1234]
],
"serviceAccountScopes": [
"https://www.googleapis.com/auth/spreadsheets"
],
"serviceAccountJson": {
"type": "service_account",
"project_id": "project-id",
"private_key_id": "key-id",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
"client_email": "service-account@project-id.iam.gserviceaccount.com",
"client_id": "123456789",
"token_uri": "https://oauth2.googleapis.com/token"
}
}
```
## OAuth postup
1. Zavolej `GET /google/oauth/scopes` a vyber scopes podle sluzeb.
2. Zavolej `GET /google/oauth/authorize-url?redirectUri=<callback>&scopes=<scopes>`.
3. Otevri `authorizationUrl` z odpovedi v prohlizeci.
4. Google presmeruje na `redirectUri?code=...`.
5. Vymen code pres `POST /google/oauth/token`.
6. Access token posilej jako `Authorization: Bearer <access_token>`.
Priklad vymeny code:
```json
{
"grantType": "authorization_code",
"code": "code-from-google-redirect",
"redirectUri": "https://example.test/oauth/callback"
}
```
## Kde vzit ID
- `calendarId`: `GET /google/calendar/calendars`, hlavni kalendar lze volat jako `primary`.
- `spreadsheetId`: `GET /google/sheets/spreadsheets`, hodnota je `files[].id`.
- `sheetId`: `GET /google/sheets/spreadsheets/{spreadsheetId}/sheets`, hodnota je `sheets[].properties.sheetId`.
- A1 range pro Sheets hodnoty: pouzij `sheets[].properties.title`, napr. `Sheet1!A1:B10`.
- `fileId`: `GET /google/drive/files`, hodnota je `files[].id`.
- `messageId`: `GET /google/gmail/messages`, hodnota je `messages[].id`.
- `documentId`, `presentationId`: u Docs/Slides jde o ID Drive souboru.
Reference in New Issue View Git Blame Copy Permalink