Öğretici - Uygulamalarınızdaki ilkelerinizden yararlanmak için Microsoft Purview API'lerini kullanma

Kurumsal yapay zeka uygulamaları dahil olmak üzere tüm uygulamalar, veri sızıntılarına, yetkisiz erişime ve uyumluluk ihlallerine karşı koruma gerektiren hassas verileri işler. Microsoft Purview ilkeleri kuruluşların hassas bilgileri korumasına yardımcı olur. uygulamalarınız, Microsoft Purview ilkelerinin uygulamanızın güvenlik duruşunu desteklediğinden emin olmak için Microsoft Purview API'leriyle tümleştirebilir.

Bu makalede, ilkelerinizden yararlanmak için Microsoft Purview API'lerini mevcut kurumsal uygulamanıza nasıl ekleyebileceğinize ilişkin bir kılavuz sağlanır. Bu makalede kullanılan örnek bir GenAI uygulamasıdır, ancak aynı kavramlar yapay zeka olmayan uygulamalara kolayca uygulanabilir. Bu kılavuzun sonunda şunları anlayacaksınız:

  • Uygulamanızda gerçekleştirdikleri bir etkinlik için bilinen bir kullanıcının Purview API'lerini ne zaman ve nasıl çağıracaklarını öğrenin.
  • Kullanıcı girişlerini ve uygulama çıkışlarını (örneğin, istemler ve yapay zeka yanıtları veya kullanıcı tarafından gönderilen metin ve oluşturulan içerik) bu ilkelerle karşılaştırarak değerlendirin.
  • Uygulamanızda kiracınızdaki ilke değişikliklerini engelleme veya güncel tutma gibi ilke eylemlerini zorunlu tutun.

Note

Microsoft Purview'a veri göndermek ve bu verilerle ilişkili Purview ilkelerini desteklemek için Microsoft Purview API'lerini kullanın. Microsoft Purview'dan veri veya analiz ayıklamak için kullanılabilecek API yok.

Prerequisites

Başlamadan önce aşağıdakilere sahip olduğunuzdan emin olun:

  • Microsoft Purview’ün yapılandırıldığı bir Azure aboneliği.

  • Uygun izinlere sahip, Microsoft Entra ID'ye kayıtlı bir uygulama.

  • Microsoft Graph API çağrıları hakkında temel bilgiler.

  • Değerlendirmek istediğiniz kullanıcı girişlerine ve uygulama çıkışlarına erişim (örneğin, Bir GenAI uygulamasındaki istemler ve yanıtlar veya bir iş kolu uygulaması tarafından yüklenen/indirilen metin).

  • Uçtan uca test için Microsoft Purview portalı ilkeler oluşturun. Mevcut ilkeler hakkında daha fazla bilgi için bkz. Entra'ya kayıtlı yapay zeka uygulamaları için veri güvenliğini ve uyumluluğu yönetmek üzere Microsoft Purview kullanma.

    Important

    Entra-registered uygulamanız için geçerli olan bir DLP ilkesi oluşturmak için PowerShell cmdlet'ini New-DlpComplianceRule kullanmanız gerekir. Microsoft Purview portalı şu anda Entra kayıtlı uygulamalar için DLP ilkeleri oluşturmayı desteklemez. Daha fazla bilgi için bkz. New-DlpComplianceRule.

Microsoft Graph kullanmaya başlama

Microsoft Graph kullanmaya tamamen yeniyseniz bkz. Microsoft Graph Temel Bilgiler.

Aşağıdaki adımlar API ile denemeler oluşturmanıza yardımcı olur. Uygulamanızın üretim dağıtımını planlamak için bu adımları kullanmayın.

  1. Uygulamanızla tümleştirmek için Microsoft Graph'deki Microsoft Purview API'leri hakkında bilgi edinin. Bu API'ler bu makalenin devamında ayrıntılı olarak açıklanmıştır.

  2. Entra Yöneticinizin uygulamanızı Entra'ya kaydetmesini sağlayın. Şirketinizin ilkesine bağlı olarak, bir uygulamayı kaydetmenize izin verebilir veya kayıt işlemini izlemeniz gerekebilir. Kiracınız için izlenecek süreci anlamak için Entra yöneticinize danışın. Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

  3. Uygulamanızı gerekli izinlerle yapılandırın. Uygulamanızın Microsoft Graph belirteci istediğinde bu izinleri istediğinden emin olun. Örneğin, Content.Process.User ve ProtectionScopes.Compute.User izinlerini uygulamanıza atayabilirsiniz. Daha fazla bilgi için bkz. Microsoft Graph izin başvurusu ve uygulamaları, kaynakları ve iş yüklerini Microsoft Entra ID ile yetkilendirme.

  4. Kiracı yöneticinizin Microsoft Purview ilkelerini ve ayarlarını yapılandırmalarını sağlayın. Daha fazla bilgi için bkz. Özel yapay zeka uygulamaları için AI için Veri Güvenliği Duruş Yönetimi’nde (DSPM) Microsoft Purview çözümlerini yapılandırma. YöneticinizIn New-DlpComplianceRule , Entra kayıtlı uygulamalarınız için DLP ilkeleri oluşturmak için PowerShell cmdlet'ini kullanması gerekir. Microsoft Purview portalı bu senaryoyu desteklemez.

  5. Uygulamanızı test edin. Daha fazla bilgi için bkz. Purview API'sini kullanarak yapay zeka uygulamasını test etme.

Microsoft Purview API tümleştirmesine genel bakış

Uygulamanız, Microsoft Purview ilkelerinizi desteklemek için iki önemli API çağrısı gerçekleştirir:

  1. Compute protection scopes: Belirli bir kullanıcı için hangi kullanıcı etkinliklerinin (uploadText, downloadText, uploadFile, downloadFile) ilke değerlendirmesi gerektirdiğini belirler.
  2. Process content: Uygulamanız, ilke değerlendirmesi için bir içerik etkinliği gönderir ve uygulamanızın zorunlu kılması gereken ilke eylemlerini döndürür (ilke değişikliklerini engelleme veya algılama gibi).

Aşağıdaki bölümlerde kod örnekleri ve yanıtların nasıl işleneceğini içeren adım adım uygulama yönergeleri sağlanır.

Bu API çağrılarını yapan bir tanıtım uygulamasının ayrıntılı bir kılavuzu için Microsoft Reactor videosuna bakın.

1. Adım: Kullanıcı için koruma kapsamlarını hesaplayın

İlk adım, uygulamanızda gerçekleştirebileceği etkinliklere (metin girişi/istemleri yükleme veya yapay zeka yanıtlarını indirme gibi) bağlı olarak belirli bir kullanıcıya hangi ilkelerin ve kısıtlamaların uygulanacağını belirlemektir. Buna kullanıcının koruma kapsamını hesaplama adı verilir.

Koruma kapsamları, kiracıdaki kullanıcıya uygulanan ilkelerin soyutlamasıdır. Kullanıcının uygulamanızda gerçekleştirdiği belirli bir kullanıcı ve etkinlik için koruma kapsamını hesaplamak istiyorsunuz. Koruma kapsamı, uygulamanın daha sonra gerçekleştirmesi gereken eylemi gösterir. Bu eylem değerlendirilebilir ve engellenebilir, değerlendirilebilir ve engellenemez ya da değerlendirme gerekmez.

Note

Kullanıcı kimlik doğrulamasının hemen ardından uygulamanızın İşlem koruma kapsamlarını çağırmasını öneririz. protectionScopes/compute öğesini aramak için kullanıcının Entra ID’sine sahip olmanız gerekir.

Yalnızca kullanıcının userPrincipalName öğesine sahipseniz, nesne kimliğini almak için aşağıdaki URL'yi kullanın.

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

İşte protectionScopes/compute için bir istek örneği.

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"
      }
   ]
}

Koruma kapsamını hesaplamak için önceki çağrıda, kullanıcının uygulamanızda gerçekleştirdiği kullanıcı etkinliklerini eklemeniz gerekir. Kabul edilen kullanıcı etkinlikleri şunlardır:

  • uploadText - Kullanıcılar uygulamaya metin girişi gönderir (örneğin, yapay zekaya gönderilen bir istem, sohbet uygulamasındaki bir ileti veya forma yapıştırılan metin).
  • downloadText - uygulamanın kullanıcıya döndürdüğü metin tabanlı çıkış (örneğin, yapay zeka yanıtı veya oluşturulan belge gövdesi).
  • uploadFile - kullanıcı uygulamaya bir dosya gönderir (örneğin, işleme istemine eklenmiş bir dosya).
  • downloadFile - Uygulama tarafından kullanıcıya döndürülen bir dosya (örneğin, yapay zeka tarafından oluşturulan veya bir iş kolu uygulaması tarafından dışarı aktarılan bir dosya).

Kullanıcı etkinlikleri hakkında daha fazla bilgi için bkz. userActivityTypes değerleri.

Koruma kapsamlarını hesaplama çağrısı, policyUserScopes öğelerinden oluşan bir koleksiyon döndürür. Burada 2 koruma kapsamına sahip bir yanıt örneği verilmiştir.

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": []
    }
  ]
}

Uygulamanızın bu yanıtı ayrıştırarak hangi kullanıcı etkinliğinin (örneğin, uploadText) kullanıcı tarafından gönderilen veya kullanıcıya gönderilen içerikte ilke değerlendirmesi gerektirdiğini belirlemesi önemlidir.

Döndürülen policyUserScopes koleksiyonu boşsa: Kullanıcı etkinliği için kullanıcıya hiçbir ilke uygulanmaz. Bu etkinlik için bu kullanıcıya hiçbir ilke uygulanmadığında, denetim uyumluluğu ve anomali algılama için etkinlikleri günlüğe kaydetmek için İçerik etkinliğini çağırmanızı öneririz. Bunu uygulamanızda yapılandırılabilir bir ayar yapabilirsiniz.

policyUserScopes koleksiyonu kapsamlar içeriyorsa: Koruma kapsamları döndürüldüğünde, uygulamanızın her koruma kapsamı için activities ve executionMode değerlerini inceleyerek yanıtı ayrıştırması gerekir. Önceki örnekte, policyUserScopes koleksiyonunda 2 koruma kapsamı döndürülür.

executionMode bir kullanıcı etkinliği için belirli bir kullanıcı için hangi kısıtlamanın geçerli olduğunu belirlemenize yardımcı olur. Aşağıdaki listede için executionModegeçerli değerler gösterilmektedir:

  • evaluateOffline: processContent çağrısı sırasında içeriği bir ilkeye göre değerlendirmek için zaman uyumsuz bir çağrı yapabileceğiniz anlamına gelir.
  • evaluateInline: uygulamanızın ana iş parçacığının, çağrı processContent'den dönene kadar engellenmesi gerektiği anlamına gelir.

Daha fazla bilgi için bkz. executionMode değerleri.

Tip

protectionScopes/compute her zaman executionMode değeri evaluateOffline olan koruma kapsamları döndürüyorsa, DLP ilkenizi New-DlpComplianceRule PowerShell cmdlet’ini kullanarak oluşturduğunuzu doğrulayın. İlkenin DSPM > Koleksiyonu ilkelerinde listelendiğini ve etkinleştirildiğini onaylayın. Microsoft Purview portalı kullanıcı arabirimi aracılığıyla oluşturulan ilkeler Entra-registered uygulamaları için geçerli değildir.

, activity koruma kapsamının uygulandığı kullanıcı etkinliğini gösterir. Bir activity öğesinin birden fazla koruma kapsamında yinelendiğini fark edebilirsiniz. Örneğin, önceki örnekte uploadText öğesinin her iki koruma kapsamında da döndürüldüğüne dikkat edin. Bu durumda uygulamanızın bu kullanıcı etkinliğine daha kısıtlayıcı koruma kapsamı uygulaması gerekir.

Aşağıdaki örnekte uygulamanızın önceki döndürülen policyUserScopes koleksiyonu nasıl ayrıştıracağı gösterilmektedir:

  1. İlk koruma kapsamını ayrıştırarak aşağıdaki bilgileri görürüz:
    • uploadText (veya yapay zekaya gönderilen istemler) ve downloadText (veya yapay zekadan gelen yanıtlar) çevrimdışı olarak değerlendirilmelidir.
  2. İkinci koruma kapsamını ayrıştırırken aşağıdaki bilgileri görürüz:
    • uploadText (veya yapay zekaya gönderilen istemler) satır içinde değerlendirilmelidir.
  3. Diğer kullanıcı etkinliklerinin (uploadFile, downloadFile) hiçbiri için koruma kapsamı geçerli değildir. daha önce açıklandığı gibi İçerik etkinliğini çağırmayı göz önünde bulundurun.

Uygulamanızın bu farklı kullanıcı etkinlikleri için uygulaması gereken mantık aşağıdaki gibidir:

Kullanıcı etkinliği Uygulamanızda eylem
uploadText processContent çağrılırken ana iş parçacığını engelleyin.
downloadText processContent çağrılırken eşzamansız bir çağrı yapın.

Important

ETag değerini önbelleğe alın: protectionScopes/compute çağrısı, bu kullanıcı için koruma kapsamlarının geçerli durumunu temsil eden bir ETag üstbilgi döndürür. Uygulamanız bu değeri önbelleğe almalı ve processContent'e yapılan tüm çağrılarla göndermelidir.

2. Adım: İçeriği işleme

Ardından, kullanıcının koruma kapsamı durumuna bağlı olarak uygulamanızın processContent çağrısı gerçekleştirmesi gerekebilir.

Daha önce açıklandığı gibi, executionMode değeri evaluateInline veya evaluateOffline olan tüm kullanıcı etkinliklerinin processContent çağırması gerekir.

Aramayı yaptığınızda, kiracınızda ilke değişiklikleri yapılıp yapılmadığını belirlemek için 1. Adımda protectionScopes/compute çağrısından uygulamanızın önbelleğe aldığı ETag değerini gönderin. If-None-Match üst bilgisinde ETag değerini gönderirsiniz.

Burada processContent çağrısına bir örnek verilmiştir.

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

Konuşma/iş parçacığı uygulama yönergeleri:

  • Uygulamanız birden çok iş parçacığını veya konuşmayı destekliyorsa (örneğin, bir yapay zeka uygulamasında veya mesajlaşma uygulamasında sohbet yazışmaları), her iş parçacığı için benzersiz correlationId bir iş parçacığı kullanın.
  • Belirli bir ileti dizisinde konuşma bağlamını koruyorsanız, her kullanıcı iletisi için sequenceNumber değerini artırın (örneğin 0, 1, 2 ve benzerlerini kullanın).

İşte processContent kaynağından bir yanıt örneği.

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": []
}

Yukarıdaki örnekte uygulamanızın gerçekleştirmesi gereken iki eylem vardır:

  1. processContentResponse, modified olarak ayarlanmış olan protectionScopeState özelliğini içerir. modified kiracıdaki ilkelerin değiştiğini gösterir. İlkeler değiştiği için uygulamanız, 1. Adımda açıklandığı gibi, bu kullanıcı için yeni koruma kapsamlarını almak üzere önce protectionScopes/compute çağrısını yapmalıdır. Yeni ETag değeri önbelleğe eklediğinizden emin olun.
  2. policyActions koleksiyonu boş olmadığından, uygulamanızın hangi işlemi yapması gerektiğini belirlemek için her bir action üzerinde adım adım ilerlemesi gerekir. Bu örnekte, restrictAccess uygulamanızın kullanıcıyı istenen eylemden engellemesi gerektiği anlamına gelir. policyActions içindeki processContentResponse koleksiyon boşsa, uygulamanız istenen etkinlikle devam eder. Aracılar oluşturuyorsanız, actionrestrictAccess olarak ayarlandığında aracı, başka bir aracıyı çağırmadan önce de engellenmelidir.

Important

son çağrısınızın processContentüzerinden 60 dakika geçtiyse, kiracıda yapılan ilke değişikliklerinin artık kullanıcıya uygulanıp uygulanmadığını algılamak için İşlem koruma kapsamlarını çağırmanızı öneririz. Artık kullanıcı için geçerli olan bir değişiklik varsa, protectionScopes/compute çağrısı yeni bir ETag değeri döndürür; bu değer uygulamanızda önbelleğe alınmalı ve processContent çağrılırken kullanılmalıdır.

  • Last updated on