HTTP-aanvraag voor query's/beheer

Werkwoord en resource aanvragen

Bewerking	HTTP-woord	HTTP-resource
Query’s uitvoeren	GET	/v1/rest/query
Query’s uitvoeren	POST	/v1/rest/query
Query v2	GET	/v2/rest/query
Query v2	POST	/v2/rest/query
Beheer	POST	/v1/rest/mgmt

Als u bijvoorbeeld een beheeropdracht ('beheer') naar een service-eindpunt wilt verzenden, gebruikt u de volgende aanvraagregel:

POST https://help.kusto.windows.net/v1/rest/mgmt HTTP/1.1

Hieronder vindt u de aanvraagheaders en hoofdtekst die u wilt opnemen.

Aanvraagheaders

De volgende tabel bevat de algemene headers die worden gebruikt voor query- en beheerbewerkingen.

Standaardkoptekst	Description	Vereist/optioneel
Accept	Ingesteld op application/json	Vereist
Accept-Encoding	Ondersteunde coderingen zijn gzip en deflate	Optioneel
Authorization	Zie verificatie	Vereist
Connection	We raden u aan om Keep-Alive	Optioneel
Content-Length	U wordt aangeraden de lengte van de aanvraagbody op te geven, indien bekend	Optioneel
Content-Type	Instellen op application/json met charset=utf-8	Vereist
Expect	Kan worden ingesteld op 100-Continue	Optioneel
Host	Stel in op de gekwalificeerde domeinnaam waarnaar de aanvraag is verzonden help.kusto.windows.net(bijvoorbeeld )	Vereist

De volgende tabel bevat de algemene aangepaste headers die worden gebruikt voor query- en beheerbewerkingen. Tenzij anders aangegeven, worden deze headers alleen gebruikt voor telemetriedoeleinden en hebben ze geen invloed op de functionaliteit.

Alle headers zijn optioneel. U wordt aangeraden de x-ms-client-request-id aangepaste koptekst op te geven. In sommige scenario's, zoals het annuleren van een actieve query, is deze header vereist omdat deze wordt gebruikt om de aanvraag te identificeren.

Aangepaste koptekst	Description
x-ms-app	De (beschrijvende) naam van de toepassing die de aanvraag indient
x-ms-user	De (beschrijvende) naam van de gebruiker die de aanvraag indient
x-ms-user-id	Hetzelfde als x-ms-user
x-ms-client-request-id	Een unieke id voor de aanvraag
x-ms-client-version	De (beschrijvende) versie-id voor de client die de aanvraag indient
x-ms-readonly	Als dit is opgegeven, wordt de aanvraag in de modus Alleen-lezen uitgevoerd, waardoor deze geen langdurige wijzigingen kan aanbrengen

Aanvraagparameters

De volgende parameters kunnen worden doorgegeven in de aanvraag. Ze worden in de aanvraag gecodeerd als queryparameters of als onderdeel van de hoofdtekst, afhankelijk van of GET of POST wordt gebruikt.

Parameter	Beschrijving	Vereist/optioneel
csl	Tekst van de query of beheeropdracht die moet worden uitgevoerd	Vereist
db	Naam van de database in het bereik dat het doel is van de query of beheeropdracht	Optioneel voor sommige beheeropdrachten. Vereist voor andere opdrachten en alle query's.
properties	Biedt aanvraageigenschappen die wijzigen hoe de aanvraag wordt verwerkt en de resultaten ervan. Zie Aanvraageigenschappen voor meer informatie	Optioneel

GET-queryparameters

Wanneer GET wordt gebruikt, geven de queryparameters van de aanvraag de aanvraagparameters op.

Hoofdtekst

Wanneer POST wordt gebruikt, is de hoofdtekst van de aanvraag één JSON-document dat is gecodeerd in UTF-8, met de waarden van de aanvraagparameters.

Voorbeelden

In dit voorbeeld ziet u de HTTP POST-aanvraag voor een query.

POST https://help.kusto.windows.net/v2/rest/query HTTP/1.1

Aanvraagheaders

Accept: application/json
Authorization: Bearer ...AzureActiveDirectoryAccessToken...
Accept-Encoding: deflate
Content-Type: application/json; charset=utf-8
Host: help.kusto.windows.net
x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1
x-ms-user-id: EARTH\davidbg
x-ms-app: MyApp

Aanvraagbody

{
  "db":"Samples",
  "csl":"print Test=\"Hello, World!\"",
  "properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"},\"Parameters\":{},\"ClientRequestId\":\"MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1\"}"
}

In dit voorbeeld ziet u hoe u met behulp van curl een aanvraag maakt waarmee de bovenstaande query wordt verzonden.

1. Een token verkrijgen voor verificatie.

   Vervang , AAD_APPLICATION_IDen AAD_APPLICATION_KEY door AAD_TENANT_NAME_OR_IDde relevante waarden nadat u Microsoft Entra-toepassingsverificatie hebt ingesteld

   curl "https://login.microsoftonline.com/AAD_TENANT_NAME_OR_ID/oauth2/token" \
     -F "grant_type=client_credentials" \
     -F "resource=https://help.kusto.windows.net" \
     -F "client_id=AAD_APPLICATION_ID" \
     -F "client_secret=AAD_APPLICATION_KEY"
   

   Met dit codefragment krijgt u het bearer-token.

   {
     "token_type": "Bearer",
     "expires_in": "3599",
     "ext_expires_in":"3599", 
     "expires_on":"1578439805",
     "not_before":"1578435905",
     "resource":"https://help.kusto.windows.net",
     "access_token":"eyJ0...uXOQ"
   }
   

2. Gebruik het bearer-token in uw aanvraag voor het query-eindpunt.

   curl -d '{"db":"Samples","csl":"print Test=\"Hello, World!\"","properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"}}"}"' \
   -H "Accept: application/json" \
   -H "Authorization: Bearer eyJ0...uXOQ" \
   -H "Content-Type: application/json; charset=utf-8" \
   -H "Host: help.kusto.windows.net" \
   -H "x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1" \
   -H "x-ms-user-id: EARTH\davidbg" \
   -H "x-ms-app: MyApp" \
   -X POST https://help.kusto.windows.net/v2/rest/query
   

3. Lees het antwoord volgens deze specificatie.

Eigenschappen en queryparameters voor clientaanvragen instellen

In de volgende voorbeeldtekst declareert de query in het veld twee parameters met de csl naam n en d. De waarden voor deze queryparameters worden opgegeven in het Parameters veld onder het properties veld in de aanvraagbody. In Options het veld worden de eigenschappen van clientaanvragen gedefinieerd.

Notitie

Niet-tekenreeks- en niet-lange parameters moeten worden uitgedrukt als letterlijke KQL-waarden in tekenreeksindeling.

{
    "db": "Samples",
    "csl": "declare query_parameters (n:long, d:dynamic); StormEvents | where State in (d) | top n by StartTime asc",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        },
        "Parameters": {
            "n": 10, "d": "dynamic([\"ATLANTIC SOUTH\"])"
        }
    }
}

Zie Queryparameters voor meer informatie.