API perburuan tingkat lanjut

  • Berlaku untuk: Microsoft Defender for Endpoint

Warning

API perburuan tingkat lanjut Microsoft Defender untuk Titik Akhir sudah tua dan memiliki kemampuan terbatas. Versi YANG lebih komprehensif dari API perburuan tingkat lanjut yang dapat mengkueri lebih banyak tabel sudah tersedia di API keamanan Microsoft Graph. Untuk informasi selengkapnya, lihat Perburuan tingkat lanjut menggunakan API keamanan Microsoft Graph.

API perburuan tingkat lanjut Microsoft Defender untuk Titik Akhir beralih ke API keamanan Microsoft Graph, yang mencakup kemampuan berburu tingkat lanjut. API keamanan Microsoft Graph menyediakan cakupan data yang lebih luas, konsistensi yang ditingkatkan, dan skalabilitas yang lebih baik untuk alur kerja otomatisasi dan keamanan. Penghentian dimulai pada Januari 2026. Setelah penghentian selesai, API berburu tingkat lanjut Microsoft Defender untuk Titik Akhir tidak lagi berfungsi. Untuk garis waktu penghentian, lihat MC1220762. Untuk informasi selengkapnya untuk membantu migrasi Anda, lihat Menggunakan API keamanan Microsoft Graph.

Note

Jika Anda adalah pelanggan Pemerintah AS, gunakan URI yang tercantum dalam Microsoft Defender untuk Titik Akhir untuk pelanggan Pemerintah AS.

Tip

Untuk performa yang lebih baik, alih-alih menggunakan api.security.microsoft.com, gunakan server yang lebih dekat dengan geolokasi Anda:

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com
  • ina.api.security.microsoft.com
  • aea.api.security.microsoft.com

Keterbatasan

  • Anda hanya bisa menjalankan kueri pada data dari 30 hari terakhir.

  • Hasilnya mencakup maksimum 100.000 baris.

  • Jumlah eksekusi dibatasi per penyewa:

    • Panggilan API: Hingga 45 panggilan per menit, dan hingga 1.500 panggilan per jam.
    • Waktu eksekusi: 10 menit waktu berjalan setiap jam dan 3 jam waktu berjalan sehari.

  • Waktu eksekusi maksimal dari satu permintaan adalah 200 detik.

  • 429 respons mewakili mencapai batas kuota baik berdasarkan jumlah permintaan atau oleh CPU. Baca isi respons untuk memahami batas apa yang tercapai.

  • Ukuran hasil kueri maksimum dari satu permintaan tidak boleh melebihi 50 MB. Jika terlampaui, Permintaan Buruk HTTP 400 dengan pesan "Eksekusi kueri telah melebihi ukuran hasil yang diizinkan. Optimalkan kueri Anda dengan membatasi jumlah hasil dan coba lagi" terjadi.

Permissions

Salah satu izin berikut diperlukan untuk memanggil API ini. Untuk mempelajari selengkapnya, termasuk cara memilih izin, lihat Menggunakan API Microsoft Defender untuk Titik Akhir

Jenis izin Izin Nama tampilan izin
Application AdvancedQuery.Read.All Run advanced queries
Didelegasikan (akun kerja atau sekolah) AdvancedQuery.Read Run advanced queries

Note

Saat mendapatkan token menggunakan kredensial pengguna:

  • Pengguna harus memiliki peran yang View Data ditetapkan dalam Microsoft Entra ID.

  • Pengguna harus memiliki akses ke perangkat, berdasarkan pengaturan grup perangkat (Lihat Membuat dan mengelola grup perangkat untuk informasi selengkapnya).

    Pembuatan grup perangkat didukung pada Defender for Endpoint Plan 1 dan Plan 2.

Permintaan HTTP

POST https://api.security.microsoft.com/api/advancedqueries/run

Tajuk permintaan

Header Value
Authorization Pembawa {token}. Diperlukan.
Content-Type application/json

Badan permintaan

Dalam isi permintaan, berikan objek JSON dengan parameter berikut:

Parameter Type Deskripsi
Query Text Kueri yang akan dijalankan. Diperlukan.

Jawaban

Jika berhasil, metode ini mengembalikan 200 OK, dan objek QueryResponse dalam isi respons.

Example

Permintaan contoh

Berikut adalah contoh permintaan.

POST https://api.security.microsoft.com/api/advancedqueries/run

{"Query":"DeviceProcessEvents |where InitiatingProcessFileName =~ 'powershell.exe' |where ProcessCommandLine contains 'appdata'|project Timestamp, FileName, InitiatingProcessFileName, DeviceId|limit 2"}

Contoh tanggapan

Berikut adalah contoh responsnya.

Note

Objek respons yang ditampilkan di sini dapat dipotong untuk brevity. Semua properti akan dikembalikan dari panggilan aktual.

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}

Tip

Apakah Anda ingin mempelajari lebih lanjut? Libatkan dengan komunitas Microsoft Security di Komunitas Teknologi kami: Microsoft Defender untuk Titik Akhir Tech Community.

  • Last updated on