Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Kembangkan REST APIs menggunakan OpenAPI di API Gateway Anda dapat menggunakan API Gateway untuk mengimpor REST API dari file definisi eksternal ke API Gateway. Saat ini, API Gateway mendukung file definisi [OpenAPIv2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) dan [OpenAPIv3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md), dengan pengecualian yang tercantum dalam file. [Catatan penting Amazon API Gateway untuk REST APIs](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis) Anda dapat memperbarui API dengan menimpa dengan definisi baru, atau Anda dapat menggabungkan definisi dengan API yang ada. Anda menentukan opsi dengan menggunakan parameter `mode` kueri di URL permintaan. Untuk tutorial tentang penggunaan fitur Impor API dari konsol API Gateway, lihat[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md). **Topics** + [Impor API yang dioptimalkan tepi ke API Gateway](import-edge-optimized-api.md) + [Impor API Regional ke API Gateway](import-export-api-endpoints.md) + [Impor file OpenAPI untuk memperbarui definisi API yang ada](api-gateway-import-api-update.md) + [Mengatur properti OpenAPI `basePath`](api-gateway-import-api-basePath.md) + [AWS variabel untuk impor OpenAPI](import-api-aws-variables.md) + [Kesalahan dan peringatan dari mengimpor API Anda ke API Gateway](api-gateway-import-api-errors-warnings.md) + [Ekspor REST API dari API Gateway](api-gateway-export-api.md) # Impor API yang dioptimalkan tepi ke API Gateway Anda dapat mengimpor file definisi OpenAPI API untuk membuat API baru yang dioptimalkan tepi dengan menentukan tipe `EDGE` titik akhir sebagai input tambahan, selain file OpenAPI, ke operasi impor. Anda dapat melakukannya menggunakan konsol API Gateway AWS CLI, atau AWS SDK. Untuk tutorial tentang penggunaan fitur Impor API dari konsol API Gateway, lihat[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md). **Topics** + [Impor API yang dioptimalkan tepi menggunakan konsol API Gateway](#import-edge-optimized-api-with-console) + [Impor API yang dioptimalkan tepi menggunakan AWS CLI](#import-edge-optimized-api-with-awscli) ## Impor API yang dioptimalkan tepi menggunakan konsol API Gateway Untuk mengimpor API yang dioptimalkan tepi menggunakan konsol API Gateway, lakukan hal berikut: 1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Pilih **Buat API**. 1. Di bawah **REST API**, pilih **Impor**. 1. Salin definisi OpenAPI API dan tempelkan ke editor kode, atau pilih **Pilih file untuk memuat file** OpenAPI dari drive lokal. 1. Untuk **jenis titik akhir API, pilih Optimalisasi** **tepi**. 1. Pilih **Buat API** untuk mulai mengimpor definisi OpenAPI. ## Impor API yang dioptimalkan tepi menggunakan AWS CLI [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)Perintah berikut mengimpor API dari file definisi OpenAPI untuk membuat API baru yang dioptimalkan tepi: ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` atau dengan spesifikasi eksplisit dari parameter string `endpointConfigurationTypes` kueri untuk`EDGE`: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Impor API Regional ke API Gateway Saat mengimpor API, Anda dapat memilih konfigurasi titik akhir regional untuk API. Anda dapat menggunakan konsol API Gateway, the AWS CLI, atau AWS SDK. Saat Anda mengekspor API, konfigurasi titik akhir API tidak disertakan dalam definisi API yang diekspor. Untuk tutorial tentang penggunaan fitur Impor API dari konsol API Gateway, lihat[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md). **Topics** + [Mengimpor API regional menggunakan konsol API Gateway](#import-regional-api-with-console) + [Impor API regional menggunakan AWS CLI](#import-regional-api-with-awscli) ## Mengimpor API regional menggunakan konsol API Gateway Untuk mengimpor API titik akhir regional menggunakan konsol API Gateway, lakukan hal berikut: 1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Pilih **Buat API**. 1. Di bawah **REST API**, pilih **Impor**. 1. Salin definisi OpenAPI API dan tempelkan ke editor kode, atau pilih **Pilih file untuk memuat file** OpenAPI dari drive lokal. 1. Untuk **jenis titik akhir API**, pilih **Regional**. 1. Pilih **Buat API** untuk mulai mengimpor definisi OpenAPI. ## Impor API regional menggunakan AWS CLI [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)Perintah berikut mengimpor file definisi OpenAPI dan menetapkan tipe endpoint ke Regional: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Impor file OpenAPI untuk memperbarui definisi API yang ada Anda dapat mengimpor definisi API hanya untuk memperbarui API yang ada, tanpa mengubah konfigurasi titik akhir, serta variabel tahapan dan tahap, atau referensi ke kunci API. import-to-updateOperasi dapat terjadi dalam dua mode: menggabungkan atau menimpa. Ketika API (`A`) digabungkan ke lain (`B`), API yang dihasilkan mempertahankan definisi keduanya `A` dan `B` jika keduanya APIs tidak berbagi definisi yang bertentangan. Ketika konflik muncul, definisi metode dari API penggabungan (`A`) akan mengesampingkan definisi metode yang sesuai dari API gabungan (). `B` Misalnya, misalkan `B` telah menyatakan metode berikut untuk kembali `200` dan `206` tanggapan: ``` GET /a POST /a ``` dan `A` menyatakan metode berikut untuk kembali `200` dan `400` tanggapan: ``` GET /a ``` Saat `A` digabungkan`B`, API yang dihasilkan menghasilkan metode berikut: ``` GET /a ``` yang kembali `200` dan `400` tanggapan, dan ``` POST /a ``` yang kembali `200` dan `206` tanggapan. Menggabungkan API berguna ketika Anda telah menguraikan definisi API eksternal Anda menjadi beberapa bagian yang lebih kecil dan hanya ingin menerapkan perubahan dari salah satu bagian tersebut pada satu waktu. Misalnya, ini mungkin terjadi jika beberapa tim bertanggung jawab atas bagian API yang berbeda dan memiliki perubahan yang tersedia dengan tarif yang berbeda. Dalam mode ini, item dari API yang ada yang tidak ditentukan secara khusus dalam definisi yang diimpor dibiarkan saja. Saat API (`A`) menimpa API (`B`) lain, API yang dihasilkan mengambil definisi dari API penimpaan ()`A`. Menimpa API berguna ketika definisi API eksternal berisi definisi lengkap API. Dalam mode ini, item dari API yang ada yang tidak ditentukan secara khusus dalam definisi yang diimpor akan dihapus. Untuk menggabungkan API, kirimkan `PUT` permintaan ke`https://apigateway..amazonaws.com/restapis/?mode=merge`. Nilai parameter `restapi_id` jalur menentukan API tempat definisi API yang disediakan akan digabungkan. Cuplikan kode berikut menunjukkan contoh `PUT` permintaan untuk menggabungkan definisi OpenAPI API di JSON, sebagai payload, dengan API tertentu yang sudah ada di API Gateway. ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Operasi pembaruan penggabungan mengambil dua definisi API lengkap dan menggabungkannya bersama-sama. Untuk perubahan kecil dan bertahap, Anda dapat menggunakan operasi [pembaruan sumber daya](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Untuk menimpa API, kirimkan `PUT` permintaan ke`https://apigateway..amazonaws.com/restapis/?mode=overwrite`. Parameter `restapi_id` path menentukan API yang akan ditimpa dengan definisi API yang disediakan. Cuplikan kode berikut menunjukkan contoh permintaan penimpaan dengan muatan definisi berformat JSON: OpenAPI ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Ketika parameter `mode` kueri tidak ditentukan, penggabungan diasumsikan. **catatan** `PUT`Operasi itu idempoten, tetapi tidak atom. Itu berarti jika kesalahan sistem terjadi sebagian melalui pemrosesan, API dapat berakhir dalam keadaan buruk. Namun, mengulangi operasi berhasil menempatkan API ke status akhir yang sama seolah-olah operasi pertama telah berhasil. # Mengatur properti OpenAPI `basePath` Di [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md), Anda dapat menggunakan `basePath` properti untuk menyediakan satu atau beberapa bagian jalur yang mendahului setiap jalur yang ditentukan dalam properti. `paths` Karena API Gateway memiliki beberapa cara untuk mengekspresikan jalur sumber daya, fitur Import API menyediakan opsi berikut untuk menafsirkan `basePath` properti selama import: ignore, prepend, dan split. Di [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/), `basePath` bukan lagi properti tingkat atas. Sebagai gantinya, API Gateway menggunakan [variabel server](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) sebagai konvensi. Fitur Import API menyediakan opsi yang sama untuk menafsirkan jalur dasar selama impor. Jalur dasar diidentifikasi sebagai berikut: + Jika API tidak berisi `basePath` variabel apa pun, fitur Import API akan memeriksa `server.url` string untuk melihat apakah itu berisi jalur di luar`"/"`. Jika ya, jalur itu digunakan sebagai jalur dasar. + Jika API hanya berisi satu `basePath` variabel, fitur Import API menggunakannya sebagai jalur dasar, meskipun tidak direferensikan `server.url` dalam. + Jika API berisi beberapa `basePath` variabel, fitur Impor API hanya menggunakan yang pertama sebagai jalur dasar. ## Abaikan Jika file OpenAPI memiliki `basePath` nilai `/a/b/c` dan `paths` properti berisi `/e` dan`/f`, berikut `POST` atau `PUT` permintaan: ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` menghasilkan sumber daya berikut di API: + `/` + `/e` + `/f` Efeknya adalah memperlakukan `basePath` seolah-olah tidak ada, dan semua sumber daya API yang dideklarasikan disajikan relatif terhadap host. Ini dapat digunakan, misalnya, ketika Anda memiliki nama domain khusus dengan pemetaan API yang tidak menyertakan *Jalur Dasar* dan nilai *Tahap* yang mengacu pada tahap produksi Anda. **catatan** API Gateway secara otomatis membuat sumber daya root untuk Anda, meskipun tidak dideklarasikan secara eksplisit dalam file definisi Anda. Ketika tidak ditentukan, `basePath` mengambil secara `ignore` default. ## Prepend Jika OpenAPI file memiliki `basePath` nilai `/a/b/c` dan `paths` properti berisi `/e` dan`/f`, berikut `POST` atau `PUT` permintaan: ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` menghasilkan sumber daya berikut di API: + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` Efeknya adalah memperlakukan `basePath` sebagai menentukan sumber daya tambahan (tanpa metode) dan menambahkannya ke kumpulan sumber daya yang dideklarasikan. Ini dapat digunakan, misalnya, ketika tim yang berbeda bertanggung jawab atas bagian API yang berbeda dan `basePath` dapat mereferensikan lokasi jalur untuk setiap bagian API tim. **catatan** API Gateway secara otomatis membuat sumber daya perantara untuk Anda, meskipun sumber daya tersebut tidak dideklarasikan secara eksplisit dalam definisi Anda. ## Split Jika OpenAPI file memiliki `basePath` nilai `/a/b/c` dan `paths` properti berisi `/e` dan`/f`, berikut `POST` atau `PUT` permintaan: ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` menghasilkan sumber daya berikut di API: + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` Efeknya adalah memperlakukan bagian jalur paling atas,`/a`, sebagai awal dari setiap jalur sumber daya, dan untuk membuat sumber daya tambahan (tanpa metode) dalam API itu sendiri. Ini dapat, misalnya, digunakan ketika `a` merupakan nama panggung yang ingin Anda ekspos sebagai bagian dari API Anda. # AWS variabel untuk impor OpenAPI Anda dapat menggunakan AWS variabel berikut dalam definisi OpenAPI. API Gateway menyelesaikan variabel saat API diimpor. Untuk menentukan variabel, gunakan`${variable-name}`. Tabel berikut menjelaskan AWS variabel yang tersedia. | Nama variabel | Deskripsi | | --- | --- | | AWS::AccountId | ID AWS akun yang mengimpor API. Misalnya, 123456789012. | | AWS::Partition | AWS Partisi di mana API diimpor. Untuk AWS Wilayah standar, partisi adalahaws. | | AWS::Region | AWS Wilayah di mana API diimpor. Misalnya, us-east-2. | ## AWS variabel contoh Contoh berikut menggunakan AWS variabel untuk menentukan AWS Lambda fungsi untuk integrasi. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # Kesalahan dan peringatan dari mengimpor API Anda ke API Gateway Saat Anda mengimpor file definisi eksternal ke API Gateway, API Gateway mungkin menghasilkan peringatan dan kesalahan. Bagian berikut membahas kesalahan dan peringatan yang mungkin terjadi selama impor. ## Kesalahan selama impor Selama impor, kesalahan dapat dihasilkan untuk masalah utama seperti dokumen yang tidak validOpenAPI. Kesalahan dikembalikan sebagai pengecualian (misalnya,`BadRequestException`) dalam respons yang tidak berhasil. Ketika terjadi kesalahan, definisi API baru dibuang dan tidak ada perubahan yang dilakukan pada API yang ada. ## Peringatan selama impor Selama impor, peringatan dapat dibuat untuk masalah kecil seperti referensi model yang hilang. Jika peringatan terjadi, operasi akan dilanjutkan jika ekspresi `failonwarnings=false` kueri ditambahkan ke URL permintaan. Jika tidak, pembaruan akan diputar kembali. Secara default, `failonwarnings` diatur ke `false`. Dalam kasus seperti itu, peringatan dikembalikan sebagai bidang di [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)sumber daya yang dihasilkan. Jika tidak, peringatan dikembalikan sebagai pesan dalam pengecualian. # Ekspor REST API dari API Gateway Setelah Anda membuat dan mengonfigurasi REST API di API Gateway, menggunakan konsol API Gateway atau sebaliknya, Anda dapat mengekspornya ke file OpenAPI menggunakan API Gateway Export API, yang merupakan bagian dari Amazon API Gateway Control Service. Untuk menggunakan API Gateway Export API, Anda harus menandatangani permintaan API Anda. Untuk informasi selengkapnya tentang permintaan [penandatanganan, lihat Menandatangani permintaan AWS API](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) di *Panduan Pengguna IAM*. Anda memiliki opsi untuk menyertakan ekstensi integrasi API Gateway, serta ekstensi [Postman](https://www.postman.com), dalam file definisi OpenAPI yang diekspor. **catatan** Saat mengekspor API menggunakan AWS CLI, pastikan untuk menyertakan parameter ekstensi seperti yang ditunjukkan pada contoh berikut, untuk memastikan bahwa `x-amazon-apigateway-request-validator` ekstensi disertakan: ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` Anda tidak dapat mengekspor API jika payloadnya bukan dari `application/json` jenisnya. Jika Anda mencoba, Anda akan mendapatkan respons kesalahan yang menyatakan bahwa model tubuh JSON tidak ditemukan. ## Permintaan untuk mengekspor REST API Dengan Export API, Anda mengekspor REST API yang ada dengan mengirimkan permintaan GET, menetapkan to-be-exported API sebagai bagian dari jalur URL. URL permintaan adalah dari format berikut: ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ Anda dapat menambahkan string `extensions` kueri untuk menentukan apakah akan menyertakan ekstensi API Gateway (dengan `integration` nilai) atau ekstensi Postman (dengan `postman` nilai). Selain itu, Anda dapat mengatur `Accept` header ke `application/json` atau `application/yaml` untuk menerima output definisi API masing-masing dalam format JSON atau YAMAL. Untuk informasi selengkapnya tentang mengirimkan permintaan GET menggunakan API Gateway Export API, lihat. [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html) **catatan** Jika Anda mendefinisikan model di API Anda, model tersebut harus untuk jenis konten “application/json” agar API Gateway dapat mengekspor model. Jika tidak, API Gateway melempar pengecualian dengan pesan kesalahan “Hanya menemukan model tubuh non-JSON untuk...”. Model harus berisi properti atau didefinisikan sebagai JSONSchema tipe tertentu. ## Unduh definisi REST API OpenAPI dalam JSON Untuk mengekspor dan mengunduh REST API dalam definisi OpenAPI dalam format JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ Di sini, `` bisa jadi, misalnya,`us-east-1`. Untuk semua wilayah di mana API Gateway tersedia, lihat [Wilayah dan Titik Akhir](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region). ## Unduh definisi REST API OpenAPI dalam YAMAL Untuk mengekspor dan mengunduh REST API dalam definisi OpenAPI dalam format YAMAL: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Unduh definisi OpenAPI REST API dengan ekstensi Postman di JSON Untuk mengekspor dan mengunduh REST API dalam definisi OpenAPI dengan format Postman JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## Unduh definisi OpenAPI REST API dengan integrasi API Gateway di YAMAL Untuk mengekspor dan mengunduh REST API dalam definisi OpenAPI dengan integrasi API Gateway dalam format YAMAL: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Ekspor REST API menggunakan konsol API Gateway Setelah [menerapkan REST API ke tahap](set-up-deployments.md#create-deployment), Anda dapat melanjutkan untuk mengekspor API di tahap ke file OpenAPI menggunakan konsol API Gateway. Di panel **Tahapan** di konsol API Gateway, pilih **Tindakan tahap**, **Ekspor**. ![\[Ekspor REST API menggunakan konsol API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/export-new-console.png) Tentukan **jenis spesifikasi API**, **Format**, dan **Ekstensi** untuk mengunduh definisi OpenAPI API Anda.