OpenAPI Özelliği Sınırlamaları

Cloud Endpoints, şu anda yalnızca OpenAPI Spesifikasyonu'nun 2. sürümünü kabul etmektedir.

Aşağıdaki bölümlerde, Cloud Endpoints'te OpenAPI özelliklerinin sınırlamaları açıklanmaktadır.

Alternatif Güvenlik Gereksinimleri

Cloud Endpoints, alternatif (mantıksal YA DA) güvenlik gereksinimlerini desteklemez. Örneğin, aşağıdaki güvenlik gereksinimi listesi desteklenmez:

security:
- petstore_auth: [...]
- api_key: []

Yukarıdaki tanım, petstore_auth gereksinimlerine veya api_key gereksinimlerine uyan istekleri kabul etmek için bir işlem gerektirir.

Bununla birlikte, Cloud Endpoints ek güvenlik gereksinimi birleşmelerini (mantıksal VE) destekler. Örneğin, aşağıdaki güvenlik gereksinimi listesi desteklenir:

security:
- petstore_auth: [...]
  api_key: []

Bu tanım, petstore_auth gereksinimlerine ve api_key gereksinimlerine aynı anda uyan istekleri kabul etmek için bir işlem gerektirir.

URL Yolu Şablonu Oluşturma

Cloud Endpoints sadece eksiksiz yol segmentlerine (eğik çizgiyle "/" ayrılmış) karşılık gelen URL yolu şablonu parametrelerini destekler. Kısmi yol segmentlerine karşılık gelen URL yolu şablonu parametreleri desteklenmez.

Örneğin, aşağıdaki URL yolu şablonları desteklenir:

  • /items/{itemId}
  • /items/{itemId}/subitems

Aşağıdaki URL yolu şablonları desteklenmez ve reddedilir:

  • /items/overview.{format}
  • /items/prefix_{id}_suffix

URL kök yolundaki "/" işlemler

Cloud Endpoints, kök yolundaki "/" işlemleri içeren OpenAPI belgeleri kabul eder. Ancak kök yolundaki istekler Genişletilebilir Hizmet Proxy'si (ESP) tarafından reddedilir.

Örneğin, aşağıdaki OpenAPI belgesi snippet'i kabul edilir:

paths:
  /:
    post:
      operationId: "root"
      responses:
        200:
          description: "Success"
          schema:
            type: string

Ancak POST / için sonraki istekler aşağıdaki hatayla birlikte reddedilir:

{
   "code": 5,
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "service_control",
           "stackEntries": []
       }
   ],
   "message": "Method does not exist."
}

Parametreler, Şemalar ve Türler

Cloud Endpoints, çoğu parametre ve tür tanımlarını yoksayar.

Daha ayrıntılı olmak gerekirse Cloud Endpoints, gerekli parametre ve tür tanımlarını içeren OpenAPI belgelerini kabul eder ancak bu tanımlar gelen isteklerde uygulanmaz. Cloud Endpoints'in kabul ettiği ancak uygulamadığı tanım örneklerinin kısmi bir listesini aşağıda bulabilirsiniz.

  • Form Verisi parametreleri. Örneğin:
    parameters:
    - name: avatar
      in: formData
      description: "The avatar of the user"
      type: string
  • Gerekli parametreler. Örneğin:
    parameters:
    - name: message
      in: query
      description: "Message to send"
      required: true
      type: string
  • Dizi koleksiyonu biçimleri. Örneğin:
    parameters:
    - name: items
      in: query
      description: "List of item IDs"
      required: true
      type: array
      items:
        type: string
      collectionFormat: tsv
  • Tür bileşimi. Örneğin:
    definitions:
      base:
        properties:
          message:
            type: string
      extended:
        description: "Extends the base type"
        allOf:
        - $ref: "#/definitions/base"
        - type: object
          properties:
            extension:
              type: string
  • Durum kodu başına farklı yanıt nesneleri. Örneğin:
    responses:
      200:
        description: "Echo"
        schema:
          $ref: "#/definitions/EchoResponse"
      400:
        description: "Error"
        schema:
          type: string

Harici tür referansları

Cloud Endpoints, bir OpenAPI belgesi dışındaki türlere verilen referansları desteklemez. Örneğin, Cloud Endpoints aşağıdakileri içeren OpenAPI belgelerini reddeder:

parameters:
- name: user
  description: User details
  in: body
  schema:
    $ref: "https://example.com/mytype.json"

Bilinen hatalar

OpenAPI belgeleri reddedildi

OpenAPI belgenizi gcloud endpoints services deploy aracılığıyla dağıttığınızda Cloud Endpoints, aşağıdakileri içeren OpenAPI belgelerini reddeder:

  • Dizi gövdesi parametreleri. Örneğin:
    parameters:
    - name: message
      description: "Message to echo"
      in: body
      schema:
        type: array
        items:
          type: string

API anahtarı sınırlamaları

OpenAPI belgenizdeki güvenlik tanımları nesnesinde API anahtarı belirtirken Cloud Endpoints aşağıdakileri gerektirir:

  • name alanı key olmalıdır
  • in alanı query olmalıdır

Örneğin:

"securityDefinitions": {
  "api_key": {
    "type": "apiKey",
    "name": "key",
    "in": "query"
  }

Diğer API anahtarı güvenlik tanımı türleriyle OpenAPI belgesi dağıtırken Cloud Endpoints, bu türleri kabul edebilir ve bir uyarı verir. Ancak API anahtarı güvenlik tanımları, gelen isteklerde yoksayılır.

Bu sayfayı yararlı buldunuz mu? Lütfen görüşünüzü bildirin:

Şunun hakkında geri bildirim gönderin...

Cloud Endpoints with OpenAPI
Yardım mı gerekiyor? Destek sayfamızı ziyaret edin.