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

9.9 KiB
Raw Blame History

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.
  • 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.

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

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_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

Service account JSON

Google service account JSON neobsahuje access_token. Obsahuje hlavne client_email, private_key a token_uri. Sluzba z techto poli sama vytvori JWT assertion, zavola Google OAuth token endpoint a ziska docasny access_token.

Produktove endpointy proto lze volat primo s:

  • serviceAccountJson v body
  • X-Google-Service-Account-Json header
  • serviceAccountJsonEnv nebo X-Google-Service-Account-Json-Env, napr. GOOGLE_SERVICE_ACCOUNT_JSON

Je nutne dodat scopes:

  • serviceAccountScopes v body
  • X-Google-Service-Account-Scopes header
  • nebo GOOGLE_SCOPES

Priklad pro zapis do Sheets:

{
  "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 krok za krokem

  1. Zavolej GET /google/oauth/scopes.
  2. Vyber scopes, napr. Sheets + Drive metadata:
https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.metadata.readonly
  1. Zavolej:
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
  1. Otevri authorizationUrl z odpovedi.
  2. Po souhlasu Google presmeruje na redirectUri s query parametrem code.
  3. Code vymen:
{
  "grantType": "authorization_code",
  "code": "code-from-google-redirect",
  "redirectUri": "https://example.test/oauth/callback"
}
  1. access_token posilej do produktovych endpointu jako:
Authorization: Bearer <access_token>

Pro dlouhodobe pouziti si uloz refresh_token mimo zdrojovy kod a obnovuj token pres:

{
  "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.

Priklad volani Google Drive:

{
  "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.

Konkretni produktove endpointy

Krome obecne proxy jsou dostupne konkretni wrappery nad nejbeznejsimi Google API:

Calendar

  • GET /google/calendar/calendars
  • POST /google/calendar/calendars
  • GET /google/calendar/calendars/{calendarId}
  • PATCH /google/calendar/calendars/{calendarId}
  • DELETE /google/calendar/calendars/{calendarId}
  • GET /google/calendar/calendars/{calendarId}/events
  • POST /google/calendar/calendars/{calendarId}/events
  • GET /google/calendar/calendars/{calendarId}/events/{eventId}
  • PATCH /google/calendar/calendars/{calendarId}/events/{eventId}
  • DELETE /google/calendar/calendars/{calendarId}/events/{eventId}
  • POST /google/calendar/calendars/{calendarId}/events/{eventId}/move

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
  • POST /google/sheets/spreadsheets/{spreadsheetId}/values/append?range=Sheet1!A1
  • 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.

{
  "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
  • POST /google/drive/files
  • GET /google/drive/files/{fileId}
  • PATCH /google/drive/files/{fileId}
  • DELETE /google/drive/files/{fileId}
  • GET /google/drive/files/{fileId}/export?mimeType=application/pdf
  • GET /google/drive/files/{fileId}/permissions
  • POST /google/drive/files/{fileId}/permissions
  • DELETE /google/drive/files/{fileId}/permissions/{permissionId}

Gmail

  • GET /google/gmail/profile
  • GET /google/gmail/messages
  • GET /google/gmail/messages/{messageId}
  • POST /google/gmail/messages/send
  • GET /google/gmail/labels
  • POST /google/gmail/labels

Docs, Slides a Forms

  • POST /google/docs/documents
  • GET /google/docs/documents/{documentId}
  • POST /google/docs/documents/{documentId}/batch-update
  • POST /google/slides/presentations
  • GET /google/slides/presentations/{presentationId}
  • POST /google/slides/presentations/{presentationId}/batch-update
  • POST /google/forms/forms
  • GET /google/forms/forms/{formId}
  • POST /google/forms/forms/{formId}/batch-update
  • GET /google/forms/forms/{formId}/responses

People a Tasks

  • GET /google/people/connections
  • GET /google/people/{resourceName}
  • POST /google/people/contacts
  • PATCH /google/people/{resourceName}
  • DELETE /google/people/{resourceName}
  • GET /google/tasks/lists
  • POST /google/tasks/lists
  • GET /google/tasks/lists/{tasklistId}/tasks
  • POST /google/tasks/lists/{tasklistId}/tasks
  • 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:

  • 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.

Reference in New Issue View Git Blame Copy Permalink