Aszinkron frissítés a REST API-val

Cikk
10/24/2023

A REST-hívásokat támogató bármely programozási nyelv használatával aszinkron adatfrissítési műveleteket hajthat végre az Azure Analysis Services táblázatos modelljein. Ez magában foglalja az írásvédett replikák szinkronizálását a lekérdezések horizontális felskálázásához.

Az adatfrissítési műveletek számos tényezőtől függően eltarthatnak, beleértve az adatmennyiséget, a partíciók használatával végzett optimalizálás szintjét stb. Ezeket a műveleteket hagyományosan olyan meglévő metódusokkal hívták meg, mint a TOM (táblázatos objektummodell), a PowerShell-parancsmagok vagy a TMSL (táblázatos modellszkriptnyelv) használata. Ezek a módszerek azonban gyakran megbízhatatlan, hosszú ideig futó HTTP-kapcsolatokat igényelhetnek.

Az Azure Analysis Services REST API-ja lehetővé teszi az adatfrissítési műveletek aszinkron végrehajtását. A REST API használatával az ügyfélalkalmazásokból származó, hosszú ideig futó HTTP-kapcsolatokra nincs szükség. A megbízhatósághoz egyéb beépített funkciók is tartoznak, például az automatikus újrapróbálkozások és a kötegelt véglegesítések.

Kiindulási URL-cím

Az alap URL-cím a következő formátumot követi:

https://<rollout>.asazure.windows.net/servers/<serverName>/models/<resource>/

Vegyük például az AdventureWorks nevű modellt egy, az USA nyugati azure-régiójában található kiszolgálón myserver. A kiszolgáló neve:

asazure://westus.asazure.windows.net/myserver

A kiszolgálónév alap URL-címe a következő:

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/

Az alap URL-cím használatával az erőforrások és a műveletek a következő paraméterek alapján fűzhetők hozzá:

Diagram that shows asynchronous refresh logic.

Minden, ami s-ben végződik, gyűjtemény.
Minden, ami () végződik, függvény.
Minden más erőforrás/objektum.

A Frissítési gyűjtemény POST parancsával például végrehajthat egy frissítési műveletet:

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/refreshes

Authentication

Minden hívást hitelesíteni kell egy érvényes Microsoft Entra-azonosítóval (OAuth 2) az Engedélyezés fejlécben, és meg kell felelnie a következő követelményeknek:

A jogkivonatnak felhasználói jogkivonatnak vagy alkalmazás-szolgáltatásnévnek kell lennie.
A jogkivonatnak a megfelelő célközönséget kell beállítania https://*.asazure.windows.net.
A felhasználónak vagy alkalmazásnak megfelelő engedélyekkel kell rendelkeznie a kiszolgálón vagy a modellen a kért hívás indításához. Az engedélyszintet a modellen vagy a kiszolgálón lévő felügyeleti csoporton belüli szerepkörök határozzák meg.

Fontos

Jelenleg kiszolgálói rendszergazdai szerepkör-engedélyekre van szükség.

POST /refreshs

Frissítési művelet végrehajtásához a /refreshes gyűjtemény POST parancsával adjon hozzá egy új frissítési elemet a gyűjteményhez. A válasz Hely fejléce tartalmazza a frissítés azonosítóját. Az ügyfélalkalmazás szükség esetén később leválaszthatja és ellenőrizheti az állapotot, mert aszinkron.

Egyszerre csak egy frissítési műveletet fogad el egy modell. Ha egy aktuális frissítési művelet fut, és egy másik el van küldve, a rendszer visszaadja a 409-et ütköző HTTP-állapotkódot.

A test a következőhöz hasonlíthat:

{
    "Type": "Full",
    "CommitMode": "transactional",
    "MaxParallelism": 2,
    "RetryCount": 2,
    "Objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Parameters

A paraméterek megadása nem kötelező. Az alapértelmezett érték lesz alkalmazva.

Name	Type	Description	Alapértelmezett
`Type`	Enum	A végrehajtandó feldolgozás típusa. A típusok a TMSL frissítési parancstípusaihoz igazodnak: teljes, clearValues, calculate, dataOnly, automatic és defragment. A hozzáadás típusa nem támogatott.	automatikus
`CommitMode`	Enum	Meghatározza, hogy az objektumok kötegekben lesznek-e véglegesítésben, vagy csak akkor, ha elkészültek. A módok a következők: alapértelmezett, tranzakciós, részleges hozzáférés.	Tranzakciós
`MaxParallelism`	Int	Ez az érték határozza meg, hogy hány szálon futtassa párhuzamosan a feldolgozási parancsokat. Ez az érték a MaxParallelism tulajdonsághoz igazodik, amely a TMSL Sequence parancsban vagy más metódusok használatával állítható be.	10
`RetryCount`	Int	Azt jelzi, hogy a művelet hányszor próbálkozik újra a sikertelenség előtt.	0
`Objects`	Tömb	Feldolgozandó objektumok tömbje. Minden objektum a következőket tartalmazza: "table" a teljes tábla vagy "tábla" és "partíció" feldolgozásakor egy partíció. Ha nincs megadva objektum, a teljes modell frissül.	A teljes modell feldolgozása

A CommitMode értéke a partialBatch. Olyan nagy adathalmazok kezdeti betöltésekor használatos, amelyek akár órákat is igénybe vehetnek. Ha a frissítési művelet egy vagy több köteg sikeres véglegesítése után meghiúsul, a sikeresen véglegesített kötegek véglegesítve maradnak (a sikeresen véglegesített kötegek nem lesznek visszaállítva).

Megjegyzés:

Íráskor a köteg mérete a MaxParallelism érték, de ez az érték változhat.

Állapotértékek

Állapotérték	Leírás
`notStarted`	A művelet még nem indult el.
`inProgress`	A művelet folyamatban van.
`timedOut`	A művelet a felhasználó által megadott időtúllépés alapján időtúllépést vett fel.
`cancelled`	Felhasználó vagy rendszer megszakította a műveletet.
`failed`	A művelet nem sikerült.
`succeeded`	A művelet sikeres volt.

GET /refreshes/<refreshId>

A frissítési művelet állapotának ellenőrzéséhez használja a GET parancsot a frissítésazonosítón. Íme egy példa a válasz törzsére. Ha a művelet folyamatban van, inProgress a rendszer állapotban adja vissza.

{
    "startTime": "2017-12-07T02:06:57.1838734Z",
    "endTime": "2017-12-07T02:07:00.4929675Z",
    "type": "full",
    "status": "succeeded",
    "currentRefreshType": "full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "succeeded"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "succeeded"
        }
    ]
}

GET /refreshs

A modell előzményfrissítési műveleteinek listájának lekéréséhez használja a GET parancsot a /refreshes gyűjteményben. Íme egy példa a válasz törzsére.

Megjegyzés:

Íráskor a rendszer a frissítési műveletek utolsó 30 napját tárolja és adja vissza, de ez a szám változhat.

[
    {
        "refreshId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "startTime": "2017-12-07T02:06:57.1838734Z",
        "endTime": "2017-12-07T02:07:00.4929675Z",
        "status": "succeeded"
    },
    {
        "refreshId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2017-12-07T01:05:54.157324Z",
        "endTime": "2017-12-07T01:05:57.353371Z",
        "status": "succeeded"
    }
]

DELETE /refreshes/<refreshId>

Folyamatban lévő frissítési művelet megszakításához használja a DELETE parancsot a frissítésazonosítón.

POST /sync

A frissítési műveletek elvégzése után előfordulhat, hogy szinkronizálni kell az új adatokat a lekérdezések horizontális felskálázásához használt replikákkal. Modell szinkronizálási műveletének végrehajtásához használja a POST parancsot a /sync függvényen. A válasz Hely fejléce tartalmazza a szinkronizálási művelet azonosítóját.

GET /sync állapot

A szinkronizálási művelet állapotának ellenőrzéséhez használja a műveletazonosítót paraméterként átadó GET parancsot. Íme egy példa a válasz törzsére:

{
    "operationId": "cd5e16c6-6d4e-4347-86a0-762bdf5b4875",
    "database": "AdventureWorks2",
    "UpdatedAt": "2017-12-09T02:44:26.18",
    "StartedAt": "2017-12-09T02:44:20.743",
    "syncstate": 2,
    "details": null
}

Értékek a következőhöz syncstate:

0: Replikálás. Az adatbázisfájlokat a rendszer egy célmappába replikálja.
1: Rehidratálás. Az adatbázis rehidratálása írásvédett kiszolgálópéldányokon történik.
2: Befejeződött. A szinkronizálási művelet sikeresen befejeződött.
3: Nem sikerült. A szinkronizálási művelet nem sikerült.
4: Véglegesítés. A szinkronizálási művelet befejeződött, de karbantartási lépéseket hajt végre.

Kódminta

Íme egy C#-kódminta az első lépésekhez, a RestApiSample a GitHubon.

A kódminta használata

Klónozza vagy töltse le az adattárat. Nyissa meg a RestApiSample-megoldást.
Keresse meg a vonalügyfélt . BaseAddress = ... és adja meg az alap URL-címet.

A kódminta szolgáltatásnév-hitelesítést használ.

Service principal

A szolgáltatásnév beállításáról és a szükséges engedélyek azure AS-ben való hozzárendeléséről további információt a Szolgáltatásnév létrehozása – Azure Portal és szolgáltatásnév hozzáadása a kiszolgálói rendszergazdai szerepkörhöz című témakörben talál. A lépések elvégzése után hajtsa végre a következő további lépéseket:

A kódmintában keresse meg a sztringszolgáltatót = ..., és cserélje le a szervezet bérlőazonosítójára.
Megjegyzés/megjegyzés feloldása, hogy a ClientCredential osztály a cred objektum példányosítására szolgáljon. Győződjön meg arról, hogy az alkalmazásazonosító> és <az <alkalmazáskulcs> értékei biztonságosan elérhetők, vagy tanúsítványalapú hitelesítést használnak a szolgáltatásnevekhez.
Futtassa a mintát.

Kapcsolódó információk

Példák
REST API

Share via