Estensioni OpenAPI

Cloud Endpoints accetta un insieme di estensioni specifiche di Google alla specifica OpenAPI che configurano i comportamenti di Extensible Service Proxy (ESP), Extensible Service Proxy V2 (ESPv2) e Service Control. Questa pagina descrive le estensioni specifiche di Google alla specifica OpenAPI.

Sebbene gli esempi riportati di seguito siano in formato YAML, è supportato anche JSON.

Convenzione di denominazione

Le estensioni OpenAPI di Google hanno nomi che iniziano con il prefisso x-google-.

x-google-allow

x-google-allow: [configured | all]

Questa estensione viene utilizzata a livello superiore di una specifica OpenAPI per indicare quali percorsi URL devono essere consentiti tramite ESP.

I valori possibili sono configured e all.

Il valore predefinito è configured, il che significa che solo i metodi API elencati nella specifica OpenAPI vengono pubblicati tramite ESP.

Quando viene utilizzato all, le chiamate non configurate, con o senza chiave API o autenticazione utente, passano attraverso ESP alla tua API.

ESP elabora le chiamate alla tua API in modo sensibile alle maiuscole. Ad esempio, ESP considera /widgets e /Widgets come metodi API diversi.

Quando viene utilizzato all, devi prestare particolare attenzione in due aree:

• Qualsiasi chiave API o regole di autenticazione.
• Il routing del percorso del backend nel servizio.

Come best practice, ti consigliamo di configurare l'API in modo da utilizzare il routing dei percorsi sensibili alle maiuscole. Se utilizzi il routing sensibile alle maiuscole, l'API restituisce un codice di stato HTTP 404 quando il metodo richiesto nell'URL non corrisponde al nome del metodo dell'API elencato nella specifica OpenAPI. Tieni presente che i framework per applicazioni web come Node.js Express dispongono di un'impostazione per attivare o disattivare il routing sensibile alle maiuscole. Il comportamento predefinito dipende dal framework in uso. Ti consigliamo di rivedere le impostazioni del tuo framework per assicurarti che il routing sensibile alle maiuscole sia abilitato. Questo consiglio è in linea con la specifica OpenAPI 2.0 che afferma: "Tutti i nomi di campo nella specifica sono sensibili alle maiuscole".

Esempio

Supponiamo che:

• L'opzione x-google-allow è impostata su all.
• Il metodo API widgets è elencato nella specifica OpenAPI, ma non Widgets.
• Hai configurato la specifica OpenAPI in modo che richieda una chiave API.

Poiché widgets è elencato nella specifica OpenAPI, ESP blocca la seguente richiesta perché non ha una chiave API:

https://my-project-id.appspot.com/widgets

Poiché Widgets non è elencato nella specifica OpenAPI, ESP trasmette la seguente richiesta al tuo servizio senza una chiave API:

https://my-project-id.appspot.com/Widgets/

Se la tua API utilizza il routing sensibile alle maiuscole (e non hai indirizzato le chiamate a "Widgets " a nessun codice), il backend dell'API restituisce un 404. Tuttavia, se utilizzi il routing senza distinzione tra maiuscole e minuscole, il backend dell'API instrada questa chiamata a "widgets".

Linguaggi e framework diversi hanno metodi diversi per controllare la sensibilità alle maiuscole e il routing. Per maggiori dettagli, consulta la documentazione del tuo framework.

x-google-backend

L'estensione x-google-backend specifica come instradare le richieste a backend locali o remoti. L'estensione può essere specificata a livello superiore e/o a livello di operazione di una specifica OpenAPI.

Per impostazione predefinita, ESP è configurato per eseguire il proxy di tutto il traffico su un singolo backend locale. L'indirizzo del backend locale è specificato dal --backend flag (il valore predefinito è http://127.0.0.1:8081). Puoi utilizzare l'estensione x-google-backend per ignorare questo comportamento predefinito e specificare uno o più backend locali o remoti che possono ricevere richieste.

L'estensione x-google-backend può anche configurare altre impostazioni per i backend locali e remoti, come l'autenticazione e i timeout. Tutte queste configurazioni possono essere applicate in base all'operazione.

L'estensione x-google-backend contiene i seguenti campi:

address

address: URL

Facoltativo. L'URL del backend di destinazione. Lo schema dell'indirizzo deve essere http o https.

Quando il routing avviene verso backend remoti (serverless), l'indirizzo deve essere impostato e la parte dello schema deve essere https.

Se un'operazione utilizza x-google-backend, ma non specifica address, ESPv2 indirizzerà le richieste al backend locale specificato dal flag --backend.

jwt_audience | disable_auth

Deve essere impostata solo una di queste due proprietà.

Se un'operazione utilizza x-google-backend, ma non specifica jwt_audience o disable_auth, ESPv2 imposterà automaticamente jwt_audience in modo che corrisponda a address. Se address non è impostato, ESPv2 imposterà automaticamente disable_auth su true.

jwt_audience

jwt_audience: string

Facoltativo. Il segmento di pubblico JWT specificato quando ESPv2 ottiene un token ID istanza, che viene poi utilizzato per effettuare la richiesta di backend di destinazione.

Quando configuri Endpoints per Serverless, il backend remoto deve essere protetto in modo da consentire solo il traffico da ESPv2. ESPv2 aggancia un token ID istanza all'intestazione Authorization durante il proxy delle richieste. Il token ID istanza rappresenta l'account di servizio di runtime utilizzato per eseguire il deployment di ESPv2. Il backend remoto può quindi verificare che la richiesta provenga da ESPv2 in base a questo token allegato.

Ad esempio, un backend remoto di cui è stato eseguito il deployment su Cloud Run può utilizzare IAM per:

1. Limita le invocazioni non autenticate revocando roles/run.invoker dal principale allUsers speciale.
2. Consenti solo a ESPv2 di invocare il backend concedendo il ruolo roles/run.invoker all'account di servizio di runtime ESPv2.

Per impostazione predefinita, ESPv2 crea il token ID istanza con un pubblico JWT corrispondente al campo address. La specifica manuale di jwt_audience è obbligatoria solo quando il backend di destinazione utilizza l'autenticazione basata su JWT e il pubblico previsto è diverso dal valore specificato nel campo address. Per i backend remoti di cui è stato eseguito il deployment su App Engine o con IAP, devi eseguire l'override del pubblico JWT. App Engine e IAP utilizzano il proprio ID client OAuth come pubblico previsto.

Quando questa funzionalità è attiva, ESPv2 modifica le intestazioni nelle richieste. Se in una richiesta è già impostata l'intestazione Authorization, ESPv2:

1. Copia il valore originale in una nuova intestazione X-Forwarded-Authorization.
2. Sostituisci l'intestazione Authorization con il token ID istanza.

Pertanto, se un client API imposta l'intestazione Authorization, un backend in esecuzione dietro ESPv2 deve utilizzare l'intestazione Authorization per recuperare l'intero JWT.X-Forwarded-Authorization Il backend deve verificare il JWT in questo header, poiché ESPv2 non eseguirà la verifica se i metodi di autenticazione non sono configurati.

disable_auth

disable_auth: bool

Facoltativo. Questa proprietà determina se ESPv2 deve impedire di ottenere un token ID istanza e di allegarlo alla richiesta.

Quando configuri il backend di destinazione, ti consigliamo di non utilizzare IAP o IAM per autenticare le richieste da ESPv2 se si applica una di queste condizioni:

1. Il backend deve consentire chiamate non autenticate.
2. Il backend richiede l'intestazione Authorization originale del client API e non può utilizzare X-Forwarded-Authorization (descritto nella sezione jwt_audience).

In questo caso, imposta questo campo su true.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Facoltativo. Imposta la strategia di traduzione dei percorsi utilizzata da ESPv2 per eseguire il proxy delle richieste al backend di destinazione.

Per ulteriori dettagli sulla traduzione dei percorsi, consulta la sezione Informazioni sulla traduzione dei percorsi.

Quando x-google-backend viene utilizzato a livello superiore della specifica OpenAPI, path_translation ha per impostazione predefinita il valore APPEND_PATH_TO_ADDRESS e quando x-google-backend viene utilizzato a livello di operazione della specifica OpenAPI, path_translation ha per impostazione predefinita il valore CONSTANT_ADDRESS. Se il campo address è mancante, path_translation rimarrà non specificato e non verrà visualizzato.

deadline

deadline: double

Facoltativo. Il numero di secondi di attesa per una risposta completa da una richiesta. Le risposte che richiedono più tempo rispetto alla scadenza configurata scadranno. La scadenza predefinita è di 15.0 secondi.

I valori non positivi non verranno presi in considerazione. In questi casi, ESPv2 utilizzerà automaticamente il valore predefinito.

La scadenza non può essere disattivata, ma può essere impostata su un numero elevato, ad esempio 3600.0 per un'ora.

protocol

protocol: [ http/1.1 | h2 ]

Facoltativo. Il protocollo utilizzato per inviare una richiesta al backend. I valori supportati sono http/1.1 e h2.

Il valore predefinito è http/1.1 per i backend HTTP e HTTPS.

Per i backend HTTP sicuri (https://) che supportano HTTP/2, imposta questo campo su h2 per migliorare le prestazioni. Questa è l'opzione consigliata per i backend serverless di Google Cloud.

Attivazione del supporto dei backend in ESP

ESPv2 rileva automaticamente quando x-google-backend è configurato.

Per attivare questa funzionalità, è necessaria una modifica manuale della configurazione dell'ESP. Attiva il supporto di x-google-backend in ESP specificando l'argomento --enable_backend_routing quando esegui il container ESP. Per i runtime in cui non controlli le opzioni del contenitore ESP, questa opzione è già disponibile. Di seguito è riportato un esempio di attivazione del supporto di x-google-backend durante il deployment del contenitore ESP su GKE (questo esempio si basa sull'esempio del tutorial Endpoints su GKE):

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port", "8081",
    "--service", "SERVICE_NAME",
    "--rollout_strategy", "managed",
    "--enable_backend_routing"
  ]

Informazioni sulla traduzione dei percorsi

Poiché l'ESP gestisce le richieste, prende il percorso della richiesta originale e lo traduce prima di effettuare una richiesta al backend di destinazione. Il modo in cui avviene questa traduzione dipende dalla strategia di traduzione del percorso utilizzata. Esistono due strategie di traduzione dei percorsi:

• APPEND_PATH_TO_ADDRESS: il percorso della richiesta di backend di destinazione viene calcolato aggiungendo il percorso della richiesta originale all'URL address dell'estensione x-google-backend.
• CONSTANT_ADDRESS: il percorso della richiesta di destinazione è costante, come definito dall'URL address dell'estensione x-google-backend. Se il percorso OpenAPI corrispondente contiene parametri, il nome del parametro e il relativo valore diventano parametri di ricerca.

Esempi:

• APPEND_PATH_TO_ADDRESS
  • address: https://my-project-id.appspot.com/BASE_PATH
  • Con i parametri del percorso OpenAPI
    • Percorso OpenAPI: /hello/{name}
    • Percorso richiesta: /hello/world
    • URL richiesta di destinazione: https://my-project-id.appspot.com/BASE_PATH/hello/world
  • Senza parametri di percorso OpenAPI
    • Percorso OpenAPI: /hello
    • Percorso richiesta: /hello
    • URL richiesta di destinazione: https://my-project-id.appspot.com/BASE_PATH/hello
• CONSTANT_ADDRESS
  • address: https://us-central1-my-project-id.cloudfunctions.net/helloGET
  • Con i parametri del percorso OpenAPI
    • Percorso OpenAPI: /hello/{name}
    • Percorso richiesta: /hello/world
    • URL richiesta di destinazione: https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
  • Senza parametri di percorso OpenAPI
    • Percorso OpenAPI: /hello
    • Percorso richiesta: /hello
    • URL richiesta di destinazione: https://us-central1-my-project-id.cloudfunctions.net/helloGET

x-google-endpoints

Questa sezione descrive gli utilizzi dell'estensione x-google-endpoints.

Configurazione del DNS nel dominio cloud.goog

Se hai eseguito il deployment dell'applicazione in Compute Engine o Google Kubernetes Engine, puoi creare una voce DNS per il servizio Endpoints nel dominio cloud.goog aggiungendo quanto segue al documento OpenAPI:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

Aggiungi l'estensione x-google-endpoints al livello superiore del documento OpenAPI (non rientrato o nidificato). Devi configurare il nome di dominio nel formato: .endpoints.PROJECT_ID.cloud.goog

Ad esempio:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  target: "192.0.2.1"

Il dominio .cloud.goog è gestito da Google e condiviso dai clienti Google Cloud. Poiché gli ID progetto Google Cloud sono univoci a livello mondiale, un nome di dominio nel formato .endpoints.PROJECT_ID.cloud.goog è un nome di dominio univoco per la tua API.

Per semplicità, configura il campo host e il campo x-google-endpoints.name in modo che siano uguali. Quando esegui il deployment del documento OpenAPI, Service Management crea:

• Un servizio gestito con il nome specificato nel campo host.
• Un record A DNS che utilizza il nome e l'indirizzo IP configurati nell'estensionex-google-endpoints.

Per le API ospitate nell'ambiente flessibile di App Engine, puoi utilizzare il dominio appspot.com. Per ulteriori informazioni, consulta la sezione Configurazione degli endpoint.

Configurare ESP per consentire le richieste CORS

Se l'API viene chiamata da un'applicazione web su un'origine diversa, deve supportare la condivisione delle risorse tra origini (CORS). Per informazioni sulla configurazione di ESP per supportare CORS, consulta Aggiunta del supporto CORS a ESP.

Se devi implementare il supporto CORS personalizzato nel codice di backend, imposta allowCors: True in modo che ESP inoltri tutte le richieste CORS al codice di backend:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

Aggiungi l'estensione x-google-endpoints al livello superiore del documento OpenAPI (non rientrato o nidificato), ad esempio:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

x-google-issuer

x-google-issuer: URI | EMAIL_ADDRESS

Questa estensione viene utilizzata nella sezione securityDefinitions di OpenAPI per specificare l'emittente di una credenziale. I valori possono assumere la forma di un nome host o di un indirizzo email.

x-google-jwks_uri

x-google-jwks_uri: URI

URI della chiave pubblica del provider impostata per convalidare la firma del JSON Web Token.

ESP supporta due formati di chiavi pubbliche asimmetriche definiti dall'x-google-jwks_uriestensione OpenAPI:

• Formato dell'insieme JWK. Ad esempio:

  x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  

• X509. Ad esempio:

  x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
  

Se utilizzi un formato di chiave simmetrica, imposta x-google-jwks_uri sull'URI di un file contenente la stringa della chiave codificata in base64url.

Se ometti x-google-jwks_uri, l'ESP seguirà il protocollo OpenID Connect Discovery per rilevare automaticamente l'URI JWKS per il provider OpenID specificato. L'ESP invierà una richiesta a x-google-issuer/.well-known/openid-configuration, analizzerà la risposta JSON e leggerà l'URI JWKS dal campo jwks_uri di primo livello.

Tieni presente che l'omissione di x-google-jwks_uri comporterà tempi di avvio a freddo più lunghi, poiché l'ESP deve effettuare un'altra chiamata remota all'avvio. Pertanto, ti consigliamo di omettere questo campo solo se l'URI JWKS cambia spesso. La maggior parte dei provider OpenID certificati (come Google, Auth0 e Okta) ha URI JWKS stabili.

x-google-jwt-locations

Per impostazione predefinita, un token JWT viene passato nell'intestazione Authorization (con prefisso "Bearer "), nell'intestazione X-Goog-Iap-Jwt-Assertion o nel parametro di query access_token. Per esempi su come passare un token JWT, consulta Effettuare una chiamata autenticata a un'API Endpoints.

In alternativa, utilizza l'estensione x-google-jwt-locations nella sezione securityDefinitions di OpenAPI per fornire le posizioni personalizzate da cui estrarre il token JWT.

L'estensione x-google-jwt-locations accetta un elenco di posizioni JWT. Ogni posizione JWT contiene i seguenti campi:

Ad esempio:

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

Se vuoi supportare solo un sottoinsieme delle posizioni JWT predefinite, elencale esplicitamente nell'estensione x-google-jwt-locations. Ad esempio, per includere il supporto solo per l'intestazione Authorization con il prefisso "Bearer ":

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

x-google-audiences

x-google-audiences: STRING

Questa estensione viene utilizzata nella sezione securityDefinitions di OpenAPI per fornire un elenco di segmenti di pubblico a cui deve corrispondere il campo JWT aud durante l'autenticazione JWT. Questa estensione accetta una singola stringa con valori separati da una virgola. Gli spazi non sono consentiti tra i segmenti di pubblico. Se non è specificato, il campo JWT aud deve corrispondere al campo host nel documento OpenAPI, a meno che non venga utilizzato il flag --disable_jwt_audience_service_name_check. Se il flag viene utilizzato ex-google-audiences non è specificato, il campo JWT aud non viene selezionato.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

x-google-management

L'estensione x-google-management controlla diversi aspetti della gestione dell'API e contiene i campi descritti in questa sezione.

metrics

Utilizza metrics in combinazione con quota e x-google-quota per configurare una quota per la tua API. Una quota ti consente di controllare la frequenza con cui le applicazioni possono chiamare i metodi della tua API. Ad esempio:

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

Il campo metrics contiene un elenco con le seguenti coppie chiave-valore:

quota

Specifica il limite della quota per una metrica definita nella sezione quota. Ad esempio:

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

Il campo quota.limits contiene un elenco con le seguenti coppie chiave:valore:

STANDARD: YOUR-LIMIT-FOR-THE-METRIC

values:
  STANDARD: 5000

x-google-quota

L'estensione x-google-quota viene utilizzata nella sezione paths di OpenAPI per associare un metodo nell'API a una metrica. Ai metodi per i quali non è stato definito x-google-quota non vengono applicati limiti di quota. Ad esempio:

x-google-quota:
  metricCosts:
    read-requests: 1

L'estensione x-google-quota contiene il seguente elemento:

Esempi di quote

L'esempio seguente mostra l'aggiunta di una metrica e di un limite per le richieste di lettura e scrittura.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

x-google-api-name

Quando il servizio contiene una sola API, il nome dell'API corrisponde al nome del servizio Endpoints. Endpoints utilizza il nome specificato nel campo host del documento OpenAPI come nome del servizio. Quando il servizio contiene più di un'API, specifica i nomi delle API aggiungendo l'estensione x-google-api-name al documento OpenAPI. L'estensione x-google-api-name consente di assegnare un nome esplicito alle singole API e di stabilire il versionamento indipendente per ciascuna API.

Ad esempio, puoi configurare un servizio denominato api.example.com con due API, producer e consumer, con i frammenti di documento OpenAPI riportati di seguito:

• API Producer in producer.yaml:

  swagger: 2.0
  host: api.example.com
  x-google-api-name: producer
  info:
    version: 1.0.3
  

• API Consumer in consumer.yaml:

  swagger: 2.0
  host: api.example.com
  x-google-api-name: consumer
  info:
    version: 1.1.0
  

Puoi eseguire il deployment dei due documenti OpenAPI insieme a:

gcloud endpoints services deploy producer.yaml consumer.yaml