Tutorial - Menggunakan API Microsoft Purview untuk memanfaatkan kebijakan Anda di aplikasi Anda

Semua aplikasi, termasuk aplikasi AI Perusahaan, menangani data sensitif yang memerlukan perlindungan terhadap kebocoran data, akses tidak sah, dan pelanggaran kepatuhan. Microsoft Purview kebijakan membantu organisasi melindungi informasi sensitif. Aplikasi Anda dapat diintegrasikan dengan API Microsoft Purview untuk memastikan kebijakan Microsoft Purview mendukung postur keamanan aplikasi Anda.

Artikel ini menyediakan panduan tentang bagaimana Anda dapat menambahkan API Microsoft Purview ke aplikasi perusahaan yang ada untuk memanfaatkan kebijakan Anda. Contoh yang digunakan dalam artikel ini adalah aplikasi GenAI, tetapi konsep yang sama dapat dengan mudah diterapkan ke aplikasi non-AI. Di akhir panduan ini, Anda akan memahami:

  • Kapan dan cara memanggil API Purview untuk pengguna yang dikenal untuk aktivitas yang mereka lakukan di aplikasi Anda.
  • Evaluasi input pengguna dan output aplikasi (misalnya, perintah dan respons AI, atau teks yang dikirimkan pengguna dan konten yang dihasilkan) terhadap kebijakan tersebut.
  • Terapkan tindakan kebijakan di aplikasi Anda, seperti memblokir atau tetap mengikuti perubahan kebijakan di tenant Anda.

Note

Gunakan API Microsoft Purview untuk mengirim data ke Microsoft Purview dan mendukung kebijakan Purview yang terkait dengan data tersebut. Tidak ada API yang tersedia untuk mengekstrak data atau analitik dari Microsoft Purview.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

  • Langganan Azure dengan Microsoft Purview yang telah dikonfigurasi.

  • Aplikasi yang terdaftar di Microsoft Entra ID dengan izin yang sesuai.

  • Pemahaman dasar tentang panggilan Microsoft Graph API.

  • Akses ke input pengguna dan output aplikasi yang ingin Anda evaluasi (misalnya, perintah dan respons di aplikasi GenAI, atau teks yang diunggah/diunduh oleh aplikasi lini bisnis).

  • Untuk pengujian end-to-end, buat kebijakan di portal Microsoft Purview Anda. Untuk informasi selengkapnya tentang kebijakan yang tersedia, lihat Menggunakan Microsoft Purview untuk mengelola keamanan & kepatuhan data untuk aplikasi AI terdaftar Entra.

    Important

    Untuk membuat kebijakan DLP yang berlaku untuk aplikasi terdaftar Entra, Anda harus menggunakan New-DlpComplianceRule cmdlet PowerShell. portal Microsoft Purview saat ini tidak mendukung pembuatan kebijakan DLP untuk aplikasi terdaftar Entra. Untuk informasi selengkapnya, lihat New-DlpComplianceRule.

Cara memulai Microsoft Graph

Jika Anda sama sekali baru menggunakan Microsoft Graph, lihat Dasar-Dasar Microsoft Graph.

Langkah-langkah berikut membantu Anda bereksperimen dengan API. Jangan gunakan langkah-langkah ini untuk merencanakan penyebaran produksi aplikasi Anda.

  1. Pelajari tentang API Microsoft Purview di Microsoft Graph untuk diintegrasikan ke dalam aplikasi Anda. API ini dijelaskan secara rinci nanti dalam artikel ini.

  2. Minta admin Entra Anda untuk mendaftarkan aplikasi Anda di Entra. Tergantung pada kebijakan perusahaan Anda, mereka mungkin mengizinkan Anda mendaftarkan aplikasi atau Anda mungkin perlu mengikuti proses pendaftaran. Pastikan untuk memeriksa dengan admin Entra Anda untuk memahami proses yang harus diikuti untuk penyewa Anda. Untuk informasi selengkapnya, lihat sumber daya berikut ini:

  3. Konfigurasikan aplikasi Anda dengan izin yang diperlukan. Pastikan aplikasi Anda meminta izin ini saat meminta token dari Microsoft Graph. Misalnya, Anda dapat menetapkan izin Content.Process.User dan ProtectionScopes.Compute.User ke aplikasi Anda. Untuk informasi selengkapnya, lihat referensi izin Microsoft Graph dan Mengotorisasi aplikasi, sumber daya, dan beban kerja dengan Microsoft Entra ID.

  4. Minta admin penyewa Anda mengonfigurasi kebijakan dan pengaturan Microsoft Purview. Untuk informasi selengkapnya, lihat Mengonfigurasi solusi Microsoft Purview di Manajemen Postur Keamanan Data (DSPM) untuk AI untuk aplikasi AI kustom. Administrator Anda harus menggunakan New-DlpComplianceRule cmdlet PowerShell untuk membuat kebijakan DLP untuk aplikasi terdaftar Entra Anda. portal Microsoft Purview tidak mendukung skenario ini.

  5. Uji aplikasi Anda. Untuk informasi selengkapnya, lihat Cara menguji aplikasi AI menggunakan API Purview.

ringkasan integrasi API Microsoft Purview

Aplikasi Anda melakukan dua panggilan API utama untuk mendukung kebijakan Microsoft Purview Anda:

  1. Compute protection scopes: Menentukan aktivitas pengguna mana (uploadText, downloadText, uploadFile, downloadFile) yang memerlukan evaluasi kebijakan untuk pengguna tertentu.
  2. Process content: Aplikasi Anda mengirimkan aktivitas konten untuk evaluasi kebijakan dan mengembalikan tindakan kebijakan yang harus diterapkan aplikasi Anda (seperti memblokir atau mendeteksi modifikasi kebijakan).

Bagian berikut menyediakan panduan implementasi langkah demi langkah, termasuk contoh kode dan cara menangani respons.

Untuk panduan terperinci tentang aplikasi demo yang melakukan panggilan API ini, lihat video Microsoft Reactor.

Langkah 1: Cakupan perlindungan komputasi untuk pengguna

Langkah pertama adalah mengidentifikasi kebijakan dan pembatasan mana yang berlaku untuk pengguna tertentu berdasarkan aktivitas yang dapat mereka lakukan di aplikasi Anda (seperti mengunggah input/perintah teks atau mengunduh respons AI). Ini disebut menghitung cakupan perlindungan pengguna.

Cakupan perlindungan adalah abstraksi dari kebijakan dalam tenant yang diterapkan ke pengguna. Untuk pengguna dan aktivitas tertentu yang dilakukan pengguna di aplikasi, Anda ingin menghitung cakupan perlindungan. Cakupan perlindungan menunjukkan tindakan yang harus dilakukan aplikasi berikutnya, yang dapat dievaluasi dan diblokir, dievaluasi, dan tidak diblokir, atau tidak diperlukan evaluasi.

Note

Kami menyarankan agar segera setelah pengguna diautentikasi, aplikasi Anda memanggil cakupan perlindungan komputasi. Untuk memanggil protectionScopes/compute Anda harus memiliki Entra ID pengguna.

Jika Anda hanya memiliki userPrincipalName pengguna, gunakan URL berikut untuk mengambil ID objeknya.

GET https://graph.microsoft.com/v1.0/users/{userPrincipalName}?$select=id

Berikut adalah contoh permintaan ke protectionScopes/compute.

POST https://graph.microsoft.com/v1.0/users/7c1f8f10-cba8-4a8d-9449-db4b876d1ef70/dataSecurityAndGovernance/protectionScopes/compute
Content-type: application/json

{
   "activities": "uploadText,downloadText",
   "locations": [
      {
         "@odata.type": "microsoft.graph.policyLocationApplication",
         "value": "83ef208a-0396-4893-9d4f-d36efbffc8bd"
      }
   ]
}

Dalam panggilan sebelumnya untuk menghitung cakupan perlindungan, Anda harus menyertakan aktivitas pengguna yang dilakukan pengguna di aplikasi Anda. Aktivitas pengguna yang diterima meliputi:

  • uploadText - pengguna mengirim input teks ke aplikasi (misalnya, perintah yang dikirim ke AI, pesan di aplikasi obrolan, atau teks yang ditempelkan ke dalam formulir).
  • downloadText - output berbasis teks yang dikembalikan aplikasi kepada pengguna (misalnya, respons AI atau isi dokumen yang dihasilkan).
  • uploadFile - pengguna mengirimkan file ke aplikasi (misalnya, file yang dilampirkan ke permintaan untuk diproses).
  • downloadFile - file yang dikembalikan oleh aplikasi kepada pengguna (misalnya, file yang dihasilkan oleh AI atau diekspor oleh aplikasi lini bisnis).

Untuk informasi selengkapnya tentang aktivitas pengguna, lihat nilai userActivityTypes.

Panggilan untuk menghitung cakupan perlindungan mengembalikan kumpulan policyUserScopes. Berikut adalah contoh respons dengan 2 cakupan perlindungan.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.policyUserScope)",
  "value": [
    {
      "activities": "uploadText,downloadText",
      "executionMode": "evaluateOffline",
      "locations": [
        {
          "@odata.type": "#microsoft.graph.policyLocationApplication",
          "value": "83ef198a-0396-4893-9d4f-d36efbffc8bd"
        }
      ],
      "policyActions": []
    },
    {
      "activities": "uploadText",
      "executionMode": "evaluateInline",
      "locations": [
        {
          "@odata.type": "#microsoft.graph.policyLocationApplication",
          "value": "83ef198a-0396-4893-9d4f-d36efbffc8bd"
        }
      ],
      "policyActions": []
    }
  ]
}

Penting bahwa aplikasi Anda mengurai respons ini untuk menentukan aktivitas pengguna mana (misalnya, uploadText) memerlukan evaluasi kebijakan pada konten yang dikirimkan oleh atau dikirim ke pengguna.

Jika kumpulan policyUserScopes yang dikembalikan kosong: Tidak ada kebijakan yang berlaku untuk pengguna untuk aktivitas pengguna. Ketika tidak ada kebijakan yang berlaku untuk pengguna ini untuk aktivitas ini, sebaiknya panggil aktivitas Konten untuk mencatat aktivitas untuk kepatuhan audit dan deteksi anomali. Anda dapat menjadikannya pengaturan yang dapat dikonfigurasi di aplikasi Anda.

Jika kumpulan policyUserScopes berisi cakupan: Saat cakupan perlindungan dikembalikan, aplikasi Anda perlu mengurai respons dengan memeriksa nilai activities dan executionMode untuk setiap cakupan perlindungan. Dalam contoh sebelumnya, 2 cakupan perlindungan dikembalikan dalam koleksi policyUserScopes.

executionMode membantu Anda menentukan batasan apa yang berlaku untuk pengguna tertentu untuk aktivitas pengguna. Daftar berikut ini memperlihatkan nilai yang valid untuk executionMode:

  • evaluateOffline: berarti Anda dapat melakukan panggilan asinkron untuk mengevaluasi konten terhadap kebijakan saat memanggil processContent.
  • evaluateInline: berarti utas utama aplikasi Anda harus tetap terblokir sampai panggilan dari processContent selesai.

Untuk informasi selengkapnya, lihat nilai executionMode.

Tip

Jika protectionScopes/compute selalu mengembalikan cakupan proteksi dengan executionMode yang selalu sama dengan evaluateOffline, verifikasi bahwa Anda membuat kebijakan DLP menggunakan cmdlet PowerShell New-DlpComplianceRule. Konfirmasikan bahwa kebijakan dicantumkan dan diaktifkan dalam kebijakan Koleksi DSPM>. Kebijakan yang dibuat melalui antarmuka pengguna portal Microsoft Purview tidak berlaku untuk aplikasi terdaftar Entra.

activity menunjukkan aktivitas pengguna tempat cakupan perlindungan berlaku. Anda mungkin mendapati bahwa activity muncul berulang dalam lebih dari 1 cakupan perlindungan. Misalnya, perhatikan pada contoh sebelumnya bahwa uploadText dikembalikan di kedua cakupan perlindungan. Dalam situasi ini, aplikasi Anda harus menerapkan cakupan perlindungan yang lebih ketat untuk aktivitas pengguna tersebut.

Contoh berikut menunjukkan bagaimana aplikasi Anda akan mengurai koleksi yang dikembalikan policyUserScopes sebelumnya:

  1. Dengan mengurai cakupan perlindungan pertama, kami melihat informasi berikut:
    • uploadText (atau perintah yang dikirim ke AI) dan downloadText (atau respons dari AI) harus dievaluasi secara offline.
  2. Saat mengurai cakupan perlindungan kedua, kami melihat informasi berikut:
    • uploadText (atau prompt yang dikirim ke AI) harus dievaluasi secara inline.
  3. Untuk salah satu aktivitas pengguna lain (uploadFile, downloadFile), tidak ada cakupan perlindungan yang berlaku untuk aktivitas pengguna tersebut. Pertimbangkan untuk memanggil aktivitas Konten seperti yang dijelaskan sebelumnya.

Logika yang harus diterapkan aplikasi Anda untuk berbagai aktivitas pengguna ini adalah sebagai berikut:

Aktivitas pengguna Tindakan di aplikasi Anda
uploadText Blokir utas utama saat memanggil processContent.
downloadText Lakukan panggilan asinkron saat memanggil processContent.

Important

Simpan nilai ETag dalam cache: Pemanggilan protectionScopes/compute mengembalikan header ETag yang mewakili status terkini cakupan perlindungan untuk pengguna tersebut. Aplikasi Anda harus menyimpan nilai ini dan mengirimkannya dengan semua panggilan ke processContent.

Langkah 2: Memproses konten

Selanjutnya, berdasarkan status cakupan perlindungan pengguna, aplikasi Anda mungkin perlu memanggil processContent.

Seperti yang dijelaskan sebelumnya, setiap aktivitas pengguna dengan executionMode berupa evaluateInline atau evaluateOffline harus memanggil processContent.

Saat Anda melakukan panggilan, kirim nilai ETag yang disimpan dalam cache oleh aplikasi Anda dari panggilan ke protectionScopes/compute pada Langkah 1 untuk menentukan apakah modifikasi kebijakan telah dilakukan di tenant Anda. Anda mengirimkan nilai ETag dalam header If-None-Match.

Berikut adalah contoh panggilan ke processContent.

POST https://graph.microsoft.com/v1.0/me/dataSecurityAndGovernance/processContent
Content-Type: application/json

{
    "contentToProcess": {
       "contentEntries": [
          {
             "@odata.type": "microsoft.graph.processConversationMetadata",
             "identifier": "07785517-9081-4fe7-a9dc-85bcdf5e9075",
             "content": {
                "@odata.type": "microsoft.graph.textContent", 
                "data": "Write an acceptance letter for Alex Wilber with Credit card number 4532667785213500, ssn: 120-98-1437 at One Microsoft Way, Redmond, WA 98052"
             },
             "name":"PC Purview API Explorer message",
             "correlationId": "d63eafd2-e3a9-4c1a-b726-a2e9b9d9580d",
             "sequenceNumber": 0, 
             "isTruncated": false,
             "createdDateTime": "2025-05-27T17:23:20",
             "modifiedDateTime": "2025-05-27T17:23:20"
          }
       ],
       "activityMetadata": { 
          "activity": "uploadText"
       },
       "deviceMetadata": {
          "deviceType": "Unmanaged",
          "operatingSystemSpecifications": {
             "operatingSystemPlatform": "Windows 11",
             "operatingSystemVersion": "10.0.26100.0" 
          },
          "ipAddress": "127.0.0.1"
       },
       "protectedAppMetadata": {
          "name": "PC Purview API Explorer",
          "version": "0.2",
          "applicationLocation":{
             "@odata.type": "microsoft.graph.policyLocationApplication",
             "value": "83ef208a-0396-4893-9d4f-d36efbffc8bd"
          }
       },
       "integratedAppMetadata": {
          "name": "PC Purview API Explorer",
          "version": "0.2" 
       }
    }
}

Note

Panduan implementasi percakapan/utas:

  • Jika aplikasi Anda mendukung beberapa utas atau percakapan (misalnya, utas obrolan di aplikasi AI atau aplikasi olahpesan), gunakan unik correlationId untuk setiap utas.
  • Jika Anda mempertahankan konteks percakapan pada utas tertentu, tingkatkan sequenceNumber untuk setiap pesan pengguna (misalnya, gunakan 0, 1, 2, dan seterusnya).

Berikut adalah contoh respons dari processContent.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.processContentResponse",
  "protectionScopeState": "modified",
  "policyActions": [
    {
      "@odata.type": "#microsoft.graph.restrictAccessAction",
      "action": "restrictAccess",
      "restrictionAction": "block"
    }
  ],
  "processingErrors": []
}

Dalam contoh sebelumnya, ada dua tindakan yang harus dilakukan aplikasi Anda:

  1. processContentResponse berisi properti protectionScopeState yang disetel ke modified. modified menunjukkan bahwa kebijakan dalam penyewa telah berubah. Karena kebijakan telah berubah, aplikasi Anda harus terlebih dahulu memanggil protectionScopes/compute untuk mendapatkan cakupan perlindungan baru untuk pengguna tersebut, yang dijelaskan di Langkah 1. Pastikan Anda menyimpan cache nilai baru ETag .
  2. Karena koleksi policyActions tidak kosong, aplikasi Anda perlu memeriksa setiap action untuk menentukan tindakan yang tepat. Dalam contoh ini, restrictAccess berarti aplikasi Anda harus memblokir pengguna dari tindakan yang diminta. Jika koleksi policyActions dalam processContentResponse kosong, aplikasi Anda akan melanjutkan aktivitas yang diminta. Jika Anda membangun agen, agen juga harus memblokir sebelum memanggil agen lain ketika action diatur ke restrictAccess.

Important

Jika sudah 60 menit sejak pemanggilan terakhir Anda ke processContent, kami sarankan untuk memanggil Compute protection scopes guna mendeteksi apakah ada perubahan kebijakan yang dibuat dalam tenant yang kini berlaku bagi pengguna. Jika ada perubahan yang sekarang berlaku untuk pengguna, panggilan untuk protectionScopes/compute mengembalikan nilai baru ETag yang harus di-cache di aplikasi Anda dan digunakan saat memanggil processContent.

  • Last updated on