Pembatasan impor API dan masalah yang diketahui
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:
|
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 |
|
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:
- OpenAPI 3.0.3
- OpenAPI 3.1.0 (hanya impor)
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 |
|
PathItem |
|
Operasi |
|
Parameter |
|
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, ,null
atau kosong), nilai nama sumber daya Azure dihasilkan dengan menggabungkan metode HTTP dan templat jalur.- Contohnya,
get-foo
.
- Contohnya,
- Nilai
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 keoperationId
.
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 menjadiget-foo-bar-buzz-quix-
.
- Misalnya,
- Pangkas tanda hubung pada kedua sisi.
- Misalnya,
get-foo-bar-buzz-quix-
menjadiget-foo-bar-buzz-quix
- Misalnya,
- 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.
- Operasi baru dibuat dengan menggabungkan metode HTTP dan templat jalur, misalnya,
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 menjadiget-foo-bar-buzz-quix-
.
- Misalnya,
- Pangkas tanda hubung pada kedua sisi.
- Misalnya,
get-foo-bar-buzz-quix-
menjadiget-foo-bar-buzz-quix
- Misalnya,
- 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
, danxsd:include
tidak didukung. Sebaliknya, gabungkan impor ke dalam satu dokumen.Terkait alat sumber terbuka untuk menyelesaikan dan menggabungkan dependensi
wsdl:import
,xsd:import
, danxsd: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
MTOM
mungkin 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:service
wsdl: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.