Sumber daya bernama unik

Artikel ini membandingkan strategi kunci unik sumber daya di API Microsoft Azure dan API Microsoft Graph dan perubahan yang dilakukan pada API Microsoft Graph untuk memungkinkannya digunakan dalam infrastruktur deklaratif sebagai file templat kode, seperti file Bicep. Ini juga menjelaskan bagaimana perubahan ini dapat digunakan untuk mereferensikan sumber daya Microsoft Graph yang ada yang dibuat melalui mekanisme selain penyebaran file Bicep.

Penting

Microsoft Graph Bicep saat ini dalam PRATINJAU. Lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure untuk persyaratan hukum yang berlaku pada fitur Azure dalam versi beta, pratinjau, atau belum dirilis secara umum.

Kunci sumber daya Azure dan Microsoft Graph

API Microsoft Azure dan Microsoft Graph menggunakan mekanisme yang berbeda untuk membuat sumber daya. Perbedaan ini menjadi lebih jelas ketika mencoba mendeklarasikan kedua sumber daya ini dalam file templat Bicep yang sama.

Pola standar Microsoft Azure API untuk membuat sumber daya adalah menggunakan metode HTTP PUT dengan kunci unik yang disediakan klien yang disebut name. Operasi idempotensi ini membuat sumber daya dengan nilai yang disediakan name jika tidak ada, atau memperbarui (mengganti) jika memang ada:

PUT /resourceCollection/{nameValue}

Pola standar Microsoft Graph API untuk membuat sumber daya adalah dengan menggunakan metode HTTP POST. Metode ini tidak idempotensi dan mengembalikan kunci ID unik yang dihasilkan layanan yang disebut id.

POST /resourceCollection

Pembaruan untuk sumber daya yang ada dicapai menggunakan metode PATCH HTTP, yang tidak seperti PUT tidak menggunakan semantik pengganti.

Semantik pembuatan Microsoft Graph melayani sebagian besar pengembang dengan baik, tetapi tidak memenuhi dua persyaratan utama untuk templat file deklaratif:

• Pengulangan: Penyebaran file templat harus dijalankan beberapa kali dengan hasil yang sama, sehingga lingkungan penyebaran cocok dengan sumber daya yang dideklarasikan dalam file templat. Pengulangan ini tidak dimungkinkan untuk metode nonidempotent seperti POST.
• Kunci atau nama yang disediakan klien: Menulis dan memelihara file templat deklaratif mengharuskan mendeklarasikan nama sumber daya (atau kunci yang disediakan klien) di muka. Untuk sebagian besar API Microsoft Graph, kunci yang disediakan klien tidak dimungkinkan.

Kunci yang disediakan klien Microsoft Graph

Selain pola pembuatan standar, beberapa sumber daya Microsoft Graph dapat menentukan properti kunci alternatif untuk digunakan sebagai nama unik yang disediakan klien. Bersama dengan nama unik yang disediakan klien, sumber daya ini mendukung mekanisme "upsert" idempoten untuk membuat sumber daya jika tidak ada atau memperbaruinya jika tidak:

PATCH /resourceCollection(uniqueName='nameValue')

Saat sumber daya dibuat, kunci ID unik yang dihasilkan layanan juga diatur. Dalam kebanyakan kasus, untuk sumber daya Microsoft Graph, properti kunci alternatif ini disebut uniqueName.

Hanya sumber daya yang mengikuti pola ini yang diekspos sebagai jenis Microsoft Graph Bicep (dengan beberapa pengecualian).

Sumber daya Microsoft Graph yang ada

Sumber daya Microsoft Graph yang dibuat menggunakan metode HTTP POST, tidak memiliki kumpulan properti nama unik.

Anda mungkin ingin membawa sumber daya yang ada ke dalam file Bicep sehingga dapat dikelola seperti sumber daya lain yang dideklarasikan dalam file Bicep. Dengan melakukan isi ulang satu kali properti nama unik sumber daya yang ada, Anda dapat mendeklarasikan sumber daya tersebut, dalam file Bicep, sehingga disebarkan ulang. Atau, Anda dapat mereferensikan sumber daya dalam file Bicep menggunakan kata kunci yang ada.

Setelah properti kunci alternatif diatur, properti tersebut tidak dapat diubah.

Langkah selanjutnya

Pelajari cara mereferensikan sumber daya yang ada