Pembatasan impor API dan masalah yang diketahui

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Saat mengimpor API, Anda mungkin menemui beberapa pembatasan atau perlu mengidentifikasi dan memperbaiki masalah sebelum Anda dapat berhasil mengimpor. Dalam artikel ini, Anda akan mempelajari:

  • Perilaku API Management selama impor OpenAPI.
  • Batasan impor OpenAPI dan cara kerja ekspor OpenAPI.
  • Persyaratan dan batasan untuk impor WSDL dan WADL.

API Management selama impor OpenAPI

Selama impor OpenAPI, API Management:

  • Memeriksa secara khusus parameter string kueri yang ditandai sebagai diperlukan.
  • Secara default, mengonversi parameter string kueri yang diperlukan ke parameter templat yang diperlukan.

Jika Anda lebih suka parameter kueri yang diperlukan dalam spesifikasi diterjemahkan ke parameter kueri di API Management, nonaktifkan pengaturan Sertakan parameter kueri dalam templat operasi saat membuat API di portal. Anda juga dapat menyelesaikan ini dengan menggunakan API - Buat atau Perbarui REST API untuk mengatur properti API translateRequiredQueryParameters ke query.

Untuk operasi GET, HEAD, dan OPTIONS, API Management membuang parameter isi permintaan jika ditentukan dalam spesifikasi OpenAPI.

Batasan impor OpenAPI/Swagger

Jika Anda menerima kesalahan saat mengimpor dokumen OpenAPI Anda, pastikan Anda telah memvalidasinya sebelumnya dengan cara:

  • Menggunakan perancang di portal Azure (Desain > Front End > Editor Spesifikasi OpenAPI), atau
  • Dengan alat pihak ketiga, seperti Swagger Editor.

Umum

Persyaratan template URL

Persyaratan Deskripsi
Nama unik untuk jalur yang diperlukan dan parameter kueri Di OpenAPI:
  • Nama parameter hanya perlu unik di dalam lokasi, misalnya jalur, kueri, header.
Dalam API Management:
  • Kami mengizinkan operasi untuk dibedakan oleh parameter jalur dan kueri.
  • OpenAPI tidak mendukung pembedaan ini, jadi kami mengharuskan adanya nama parameter unik di dalam keseluruhan template URL.
Parameter URL yang ditentukan Harus menjadi bagian dari template URL.
URL file sumber yang tersedia Diterapkan ke URL server relatif.
\$ref pointer Tidak dapat mereferensikan file eksternal.

Spesifikasi OpenAPI

Versi yang didukung

API Management hanya mendukung:

  • OpenAPI versi 2.
  • OpenAPI versi 3.0.x (hingga versi 3.0.3).
  • OpenAPI versi 3.1 (hanya impor)

Batasan ukuran

Batas ukuran Deskripsi
Hingga 4 MB Saat spesifikasi OpenAPI diimpor sebaris ke API Management.
Ukuran permintaan API Azure Resource Manager Saat dokumen OpenAPI disediakan melalui URL ke lokasi yang dapat diakses dari layanan API Management Anda. Lihat Batas langganan Azure.

Ekstensi yang didukung

Satu-satunya ekstensi yang didukung adalah:

Ekstensi Deskripsi
x-ms-paths
  • Memungkinkan Anda menentukan jalur yang dibedakan berdasarkan parameter kueri di URL.
  • Tercakup dalam dokumen AutoRest.
x-servers Backport dari objek OpenAPI 3 servers untuk OpenAPI 2.

Ekstensi yang tidak didukung

Ekstensi Deskripsi
Recursion API Management tidak mendukung definisi yang ditentukan secara rekursif.
Misalnya, skema yang mengacu pada diri mereka sendiri.
Server objek Tidak didukung pada tingkat operasi API.
Produces kata kunci Menjelaskan jenis MIME yang ditampilkan oleh API.
Tidak didukung.

Ekstensi kustom

  • Diabaikan saat impor.
  • Tidak disimpan atau dicadangkan untuk ekspor.

Definisi yang tidak didukung

Definisi skema sebaris untuk operasi API tidak didukung. Definisi skema:

  • Didefinisikan dalam cakupan API.
  • Dapat dirujuk dalam permintaan operasi API atau cakupan respons.

Definisi yang diabaikan

Definisi keamanan diabaikan.

Pembatasan definisi

Saat mengimpor parameter kueri, hanya metode serialisasi array default (style: form, explode: true) yang didukung. Untuk detail selengkapnya tentang parameter kueri dalam spesifikasi OpenAPI, lihat spesifikasi serialisasi.

Parameter yang ditentukan dalam cookie tidak didukung. Anda masih dapat menggunakan kebijakan untuk mendekode dan memvalidasi konten cookie.

OpenAPI versi 2

Dukungan OpenAPI versi 2 terbatas hanya pada format JSON.

Parameter jenis "Formulir" tidak didukung. Anda masih dapat menggunakan kebijakan untuk mendekode dan memvalidasi payload application/x-www-form-urlencoded dan application/form-data.

OpenAPI versi 3.x

API Management mendukung versi spesifikasi berikut:

URL HTTPS

  • Jika beberapa servers ditentukan, API Management akan menggunakan URL HTTPS pertama yang ditemukannya.
  • Jika tidak ada URL HTTPS, URL server kosong.

Didukung

  • example

Tidak didukung

Bidang berikut disertakan dalam OpenAPI versi 3.0.x atau OpenAPI versi 3.1.x, tetapi tidak didukung:

Objek Bidang
OpenAPI externalDocs
Info summary
Komponen
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Operasi
  • externalDocs
  • callbacks
  • security
  • servers
Parameter
  • allowEmptyValue
  • style
  • explode
  • allowReserved

Mekanisme impor, pembaruan, dan ekspor OpenAPI

Umum

Definisi API yang diekspor dari layanan API Management:

  • Utamanya ditujukan untuk aplikasi eksternal yang perlu memanggil API yang dihosting di layanan API Management.
  • Tidak ditujukan untuk diimpor ke dalam layanan API Management yang sama atau berbeda.

Untuk manajemen konfigurasi definisi API di berbagai layanan/lingkungan, lihat dokumentasi mengenai penggunaan layanan API Management dengan Git.

Menambahkan API baru melalui impor OpenAPI

Untuk setiap operasi yang ditemukan dalam dokumen OpenAPI, operasi baru dibuat dengan:

  • Nama sumber daya Azure ditetapkan ke operationId.

    • Nilai operationId dinormalisasi.
    • Jika operationId tidak ditentukan (tidak ada, , nullatau kosong), nilai nama sumber daya Azure dihasilkan dengan menggabungkan metode HTTP dan templat jalur.
      • Contohnya,get-foo.

  • Nama tampilan ditetapkan ke summary.

    • summary Nilai:
      • Diimpor apa adanya.
      • Panjang dibatasi hingga 300 karakter.
    • Jika summary tidak ditentukan (tidak ada, null, atau kosong), nilai nama tampilan akan ditetapkan ke operationId.

Aturan normalisasi untuk operationId

  • Konversi ke huruf kecil.
  • Ganti setiap urutan karakter non-alfanumerik dengan satu tanda hubung.
    • Misalnya, GET-/foo/{bar}?buzz={quix} diubah menjadi get-foo-bar-buzz-quix-.
  • Pangkas tanda hubung pada kedua sisi.
    • Misalnya, get-foo-bar-buzz-quix- menjadi get-foo-bar-buzz-quix
  • Potong agar pas menjadi 76 karakter, empat karakter lebih sedikit dari batas maksimum untuk nama sumber daya.
  • Gunakan empat karakter tersisa untuk akhiran deduplikasi, jika perlu, dalam bentuk -1, -2, ..., -999.

Memperbarui API yang sudah ada melalui impor OpenAPI

Selama impor, operasi API yang ada:

  • Berubah agar sesuai dengan API yang dijelaskan dalam dokumen OpenAPI.
  • Cocok dengan operasi dalam dokumen OpenAPI dengan membandingkan nilai operationId-nya dengan nama sumber daya Azure pada operasi yang ada.
    • Jika kecocokan ditemukan, properti operasi yang ada diperbarui "di tempat".
    • Jika kecocokan tidak ditemukan:
      • Operasi baru dibuat dengan menggabungkan metode HTTP dan templat jalur, misalnya, get-foo.
      • Untuk setiap operasi baru, impor akan mencoba menyalin kebijakan dari operasi yang ada dengan metode HTTP dan templat jalur yang sama.

Semua operasi yang tidak cocok yang ada akan dihapus.

Untuk membuat impor lebih mudah diprediksi, ikuti panduan berikut:

  • Tentukan properti operationId untuk setiap operasi.
  • Tahan diri untuk tidak mengubah operationId setelah impor awal.
  • Jangan pernah mengubah operationId dan metode HTTP atau templat jalur secara bersamaan.

Aturan normalisasi untuk operationId

  • Konversi ke huruf kecil.
  • Ganti setiap urutan karakter non-alfanumerik dengan satu tanda hubung.
    • Misalnya, GET-/foo/{bar}?buzz={quix} diubah menjadi get-foo-bar-buzz-quix-.
  • Pangkas tanda hubung pada kedua sisi.
    • Misalnya, get-foo-bar-buzz-quix- menjadi get-foo-bar-buzz-quix
  • Potong agar pas menjadi 76 karakter, empat karakter lebih sedikit dari batas maksimum untuk nama sumber daya.
  • Gunakan empat karakter tersisa untuk akhiran deduplikasi, jika perlu, dalam bentuk -1, -2, ..., -999.

Ekspor API sebagai OpenAPI

Untuk setiap operasi, ini adalah:

  • Nama sumber daya Azure diekspor sebagai operationId.
  • Nama tampilan diekspor sebagai summary.

Perhatikan bahwa normalisasi operationId dilakukan pada impor, bukan ekspor.

WSDL

Anda dapat membuat API SOAP pass-through dan SOAP-to-REST dengan file WSDL.

Pengikatan SOAP

  • Hanya pengikatan SOAP dari gaya pengodean "dokumen" dan "literal" yang didukung.
  • Tidak ada dukungan untuk gaya "rpc" atau SOAP-Encoding.

Mengimpor dan menyertakan

  • Arahan wsdl:import, xsd:import, dan xsd:include tidak didukung. Sebaliknya, gabungkan impor ke dalam satu dokumen.

  • Terkait alat sumber terbuka untuk menyelesaikan dan menggabungkan dependensi wsdl:import, xsd:import, dan xsd:include dalam file WSDL, lihat repositori GitHub ini.

Spesifikasi WS-*

File WSDL yang menggabungkan spesifikasi WS-* tidak didukung.

Pesan dengan beberapa bagian

Jenis pesan ini tidak didukung.

WCF wsHttpBinding

  • Layanan SOAP yang dibuat dengan Windows Communication Foundation sebaiknya menggunakan basicHttpBinding.
  • wsHttpBinding tidak didukung.

MTOM

  • Layanan yang menggunakan MTOMmungkin berfungsi.
  • Dukungan resmi tidak ditawarkan untuk saat ini.

Rekursi

  • Jenis yang ditentukan secara rekursif tidak didukung oleh API Management.
  • Misalnya, rujuk pada array dari diri mereka sendiri.

Beberapa namespace

Beberapa namespace dapat digunakan dalam skema, tetapi hanya namespace target yang dapat digunakan untuk menentukan bagian pesan. Namespace ini digunakan untuk menentukan elemen input atau output lainnya.

Namespace selain target tidak dipertahankan saat diekspor. Meskipun Anda dapat mengimpor dokumen WSDL yang mendefinisikan bagian pesan dengan namespace lain, semua bagian pesan akan memiliki namespace target WSDL saat diekspor.

Beberapa titik akhir

File WSDL dapat menentukan beberapa layanan dan titik akhir (port) oleh satu atau beberapa wsdl:servicewsdl:port elemen. Namun, gateway API Management hanya dapat mengimpor dan mem-proksi permintaan ke satu layanan dan titik akhir. Jika beberapa layanan atau titik akhir ditentukan dalam file WSDL, identifikasi nama layanan target dan titik akhir saat mengimpor API dengan menggunakan properti wsdlSelector .

Tip

Jika Anda ingin menyeimbangkan beban permintaan di beberapa layanan dan titik akhir, pertimbangkan untuk mengonfigurasi kumpulan backend yang seimbang beban.

Larik

Transformasi SOAP-to-REST hanya mendukung array terbungkus yang ditunjukkan dalam contoh di bawah ini:

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

Untuk saat ini, belum diketahui masalah impor WADL.