Používání Azure blockchain Workbench Preview REST API

Článek
05/13/2021
8 min ke čtení

Azure blockchain Workbench Preview REST API poskytuje vývojářům a informačním pracovníkům způsob, jak vytvářet bohatou integraci aplikací blockchain. Tento článek popisuje několik scénářů použití REST API Workbench. Předpokládejme například, že chcete vytvořit vlastního klienta blockchain, který umožňuje přihlášeným uživatelům zobrazení a interakci s přiřazenými aplikacemi blockchain. Klient může použít rozhraní API blockchain Workbench k zobrazení instancí kontraktů a provedení akcí v rámci inteligentních smluv.

Koncový bod rozhraní API pro blockchain Workbench

K rozhraním API aplikace blockchain Workbench se dostanete prostřednictvím koncového bodu pro vaše nasazení. Pro získání adresy URL koncového bodu rozhraní API pro vaše nasazení:

Přihlaste se na Azure Portal.
V levém navigačním podokně vyberte skupiny prostředků.
Vyberte název skupiny prostředků, kterou jste nasadili blockchain Workbench.
Vyberte záhlaví sloupce typ k seřazení seznamu abecedně podle typu.
Existují dva prostředky s typem App Service. Vyberte prostředek typu App Service s příponou "-API".
V přehledu App Service Zkopírujte hodnotu URL , která představuje adresu URL koncového bodu rozhraní API pro nasazenou aplikaci blockchain Workbench.

Authentication

Požadavky na REST API Workbench blockchain jsou chráněné pomocí Azure Active Directory (Azure AD).

Aby bylo možné provést ověřený požadavek na rozhraní REST API, kód klienta vyžaduje ověření pomocí platných přihlašovacích údajů před voláním rozhraní API. Ověřování je sladěné mezi různými aktéry Azure AD a poskytuje vašemu klientovi přístupový token jako ověření platnosti. Token se pak pošle v hlavičce autorizace HTTP REST API požadavků. Další informace o ověřování Azure AD najdete v tématu Azure Active Directory pro vývojáře.

Příklady ověřování najdete v tématu ukázky REST API .

S využitím Postmana

Pokud chcete testovat nebo experimentovat s rozhraními API aplikace Workbench, můžete použít metodu post k zajištění volání rozhraní API pro vaše nasazení. Stáhněte si ukázku post z kolekce požadavky rozhraní API Workbench z GitHubu. Podrobnosti o ověřování a používání ukázkových požadavků rozhraní API najdete v souboru READme.

Vytvoření aplikace

K vytvoření aplikace blockchain Workbench použijete dvě volání rozhraní API. Tuto metodu můžou provádět jenom uživatelé, kteří jsou správci aplikace Workbench.

Pro nahrání souboru JSON aplikace a získání ID aplikace použijte rozhraní API pro odeslání aplikace.

Žádosti po odeslání

Pomocí parametru appFile můžete konfigurační soubor odeslat jako součást textu žádosti.

POST /api/v1/applications
Content-Type: multipart/form-data;
Authorization : Bearer {access token}
Content-Disposition: form-data; name="appFile"; filename="/C:/smart-contract-samples/HelloWorld.json"
Content-Type: application/json

Aplikace po odpovědi

V odpovědi se vrátí vytvořené ID aplikace. K přidružení konfiguračního souboru k souboru s kódem při volání dalšího rozhraní API potřebujete ID aplikace.

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

Požadavek POST kódu kontraktu

Použijte rozhraní API pro kód kontraktu , a to předáním ID aplikace a nahráním souboru kódu pro záhustotu aplikace. Datovou částí může být jeden soubor s pevnou hustotou nebo soubor. zip obsahující soubory.

Nahraďte následující hodnoty:

Parametr	Hodnota
ApplicationId	Návratová hodnota z rozhraní API pro odeslání aplikace
{ledgerId}	Index hlavní knihy Hodnota je obvykle 1. Můžete také v tabulce hlavní knihy vyhledat hodnotu.

POST /api/v1/applications/{applicationId}/contractCode?ledgerId={ledgerId}
Content-Type: multipart/form-data;
Authorization : Bearer {access token}
Content-Disposition: form-data; name="contractFile"; filename="/C:/smart-contract-samples/HelloWorld.sol"

Odpověď po odeslání kódu kontraktu

V případě úspěchu odpověď obsahuje ID vytvořeného kódu kontraktu z tabulky ContractCode.

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

Přiřazení rolí uživatelům

Pomocí přiřazení rolí aplikace předejte rozhraní API předáním ID aplikace, ID uživatele a ID aplikační role a vytvořte tak mapování uživatele na role v zadané aplikaci blockchain. Tuto metodu můžou provádět jenom uživatelé, kteří jsou správci aplikace Workbench.

Přiřazení rolí – požadavek po odeslání

Nahraďte následující hodnoty:

Parametr	Hodnota
ApplicationId	Návratová hodnota z rozhraní API pro odeslání aplikace
UserID	Hodnota ID uživatele z tabulky uživatelů
{applicationRoleId}	Hodnota ID aplikační role přidružená k ID aplikace z tabulky ApplicationRole

POST /api/v1/applications/{applicationId}/roleAssignments
Content-Type: application/json;
Authorization : Bearer {access token}

{
  "userId": {userId},
  "applicationRoleId": {applicationRoleId}
}

Přiřazení rolí po odpovědi

V případě úspěchu bude odpověď zahrnovat ID vytvořeného přiřazení role z tabulky RoleAssignment.

HTTP/1.1 200
1

Výpis aplikací

K načtení všech aplikací blockchain Workbench pro uživatele použijte aplikace získat rozhraní API . V tomto příkladu má přihlášený uživatel přístup ke dvěma aplikacím:

Žádosti o získání

GET /api/v1/applications
Authorization : Bearer {access token}

Aplikace obdrží odpověď.

V odpovědi se zobrazí všechny aplikace blockchain, ke kterým má uživatel přístup v blockchain Workbench. Správci blockchain Workbench získají každou aplikaci blockchain. Správci mimo aplikaci Workbench získají všechny aplikace blockchain, pro které mají alespoň jednu přidruženou aplikační roli nebo přidruženou roli instance inteligentního kontraktu.

HTTP/1.1 200 OK
Content-type: application/json
{
    "nextLink": "/api/v1/applications?skip=2",
    "applications": [
        {
            "id": 1,
            "name": "AssetTransfer",
            "description": "Allows transfer of assets between a buyer and a seller, with appraisal/inspection functionality",
            "displayName": "Asset Transfer",
            "createdByUserId": 1,
            "createdDtTm": "2018-04-28T05:59:14.4733333",
            "enabled": true,
            "applicationRoles": null
        },
        {
            "id": 2,
            "name": "RefrigeratedTransportation",
            "description": "Application to track end-to-end transportation of perishable goods.",
            "displayName": "Refrigerated Transportation",
            "createdByUserId": 7,
            "createdDtTm": "2018-04-28T18:25:38.71",
            "enabled": true,
            "applicationRoles": null
        }
    ]
}

Výpis pracovních postupů pro aplikaci

Použijte pracovní postupy aplikací získat rozhraní API k vypsání všech pracovních postupů zadané aplikace blockchain, ke kterým má uživatel přístup v blockchain Workbench. Každá blockchainová aplikace má jeden nebo více pracovních postupů a každý pracovní postup má nula nebo více instancí chytrých kontraktů. Pro klientskou aplikaci blockchain, která má jenom jeden pracovní postup, doporučujeme přeskočit tok uživatelského prostředí, který uživatelům umožní vybrat příslušný pracovní postup.

Žádost o pracovní postupy aplikace

GET /api/v1/applications/{applicationId}/workflows
Authorization: Bearer {access token}

Odpověď pracovních postupů aplikace

Správci blockchain Workbench získají každý pracovní postup blockchain. Správci mimo aplikaci Workbench získají všechny pracovní postupy, pro které mají alespoň jednu přidruženou roli aplikace nebo která je přidružena k roli instance inteligentního kontraktu.

HTTP/1.1 200 OK
Content-type: application/json
{
    "nextLink": "/api/v1/applications/1/workflows?skip=1",
    "workflows": [
        {
            "id": 1,
            "name": "AssetTransfer",
            "description": "Handles the business logic for the asset transfer scenario",
            "displayName": "Asset Transfer",
            "applicationId": 1,
            "constructorId": 1,
            "startStateId": 1
        }
    ]
}

Vytvoření instance kontraktu

K vytvoření nové instance inteligentních kontraktů pro pracovní postup použijte kontrakty verze V2 post API . Pokud je uživatel přidružený k roli aplikace, může vytvořit pouze novou instanci inteligentního kontraktu, pokud je uživatel přidružen k aplikační roli, která může iniciovat instanci inteligentního kontraktu pro pracovní postup.

Poznámka

V tomto příkladu se používá verze 2 rozhraní API. Rozhraní API kontraktu verze 2 poskytují pro přidružená pole ProvisioningStatus větší členitost.

Kontrakt po požadavku

Nahraďte následující hodnoty:

Parametr	Hodnota
WorkflowId	Hodnota ID pracovního postupu je ConstructorID kontraktu z tabulky pracovního postupu.
{contractCodeId}	Hodnota ID kódu kontraktu z tabulky ContractCode Proveďte korelaci ID aplikace a ID hlavní knihy pro instanci kontraktu, kterou chcete vytvořit.
ConnectionID	Hodnota ID připojení z tabulky připojení.

U textu žádosti nastavte hodnoty pomocí následujících informací:

Parametr	Hodnota
workflowFunctionID	ID z tabulky WorkflowFunction
workflowActionParameters	Páry název hodnoty dvojic parametrů předaných konstruktoru. Pro každý parametr použijte hodnotu workflowFunctionParameterID z tabulky WorkflowFunctionParameter .

POST /api/v2/contracts?workflowId={workflowId}&contractCodeId={contractCodeId}&connectionId={connectionId}
Content-Type: application/json;
Authorization : Bearer {access token}

{
  "workflowFunctionID": 2,
  "workflowActionParameters": [
    {
      "name": "message",
      "value": "Hello, world!",
      "workflowFunctionParameterId": 3
    }
  ]
}

Kontrakt po odpovědi

V případě úspěchu vrátí rozhraní API přiřazení rolí ContractActionID z tabulky ContractActionParameter.

HTTP/1.1 200 OK
4

Výpis instancí chytrých kontraktů pro pracovní postup

Pomocí kontraktů získat rozhraní API můžete zobrazit všechny instance inteligentních kontraktů pro pracovní postup. Nebo můžete uživatelům dovolit hluboko podrobně do kterékoli ze zobrazených instancí inteligentních kontraktů.

Žádost o smlouvy

V tomto příkladu předpokládejme, že by uživatel chtěl komunikovat s některou z instancí chytrých kontraktů kvůli provedení akce.

GET api/v1/contracts?workflowId={workflowId}
Authorization: Bearer {access token}

Odpověď smluv

Odpověď obsahuje seznam všech instancí inteligentních kontraktů určeného pracovního postupu. Správci aplikace Workbench získají všechny instance inteligentních kontraktů. Správci mimo Workbench získají každou instanci inteligentních kontraktů, pro kterou mají alespoň jednu přidruženou aplikační roli nebo přidruženou k roli instance inteligentního kontraktu.

HTTP/1.1 200 OK
Content-type: application/json
{
    "nextLink": "/api/v1/contracts?skip=3&workflowId=1",
    "contracts": [
        {
            "id": 1,
            "provisioningStatus": 2,
            "connectionID": 1,
            "ledgerIdentifier": "0xbcb6127be062acd37818af290c0e43479a153a1c",
            "deployedByUserId": 1,
            "workflowId": 1,
            "contractCodeId": 1,
            "contractProperties": [
                {
                    "workflowPropertyId": 1,
                    "value": "0"
                },
                {
                    "workflowPropertyId": 2,
                    "value": "My first car"
                },
                {
                    "workflowPropertyId": 3,
                    "value": "54321"
                },
                {
                    "workflowPropertyId": 4,
                    "value": "0"
                },
                {
                    "workflowPropertyId": 5,
                    "value": "0x0000000000000000000000000000000000000000"
                },
                {
                    "workflowPropertyId": 6,
                    "value": "0x0000000000000000000000000000000000000000"
                },
                {
                    "workflowPropertyId": 7,
                    "value": "0x0000000000000000000000000000000000000000"
                },
                {
                    "workflowPropertyId": 8,
                    "value": "0xd882530eb3d6395e697508287900c7679dbe02d7"
                }
            ],
            "transactions": [
                {
                    "id": 1,
                    "connectionId": 1,
                    "transactionHash": "0xf3abb829884dc396e03ae9e115a770b230fcf41bb03d39457201449e077080f4",
                    "blockID": 241,
                    "from": "0xd882530eb3d6395e697508287900c7679dbe02d7",
                    "to": null,
                    "value": 0,
                    "isAppBuilderTx": true
                }
            ],
            "contractActions": [
                {
                    "id": 1,
                    "userId": 1,
                    "provisioningStatus": 2,
                    "timestamp": "2018-04-29T23:41:14.9333333",
                    "parameters": [
                        {
                            "name": "Description",
                            "value": "My first car"
                        },
                        {
                            "name": "Price",
                            "value": "54321"
                        }
                    ],
                    "workflowFunctionId": 1,
                    "transactionId": 1,
                    "workflowStateId": 1
                }
            ]
        }
    ]
}

Výpis dostupných akcí pro kontrakt

Pomocí akce získat rozhraní API pro zobrazení dostupných uživatelských akcí podle stavu smlouvy.

Žádost o akci smlouvy

V tomto příkladu si uživatel prohlíží všechny dostupné akce pro novou vytvářenou vydanou smlouvu.

GET /api/v1/contracts/{contractId}/actions
Authorization: Bearer {access token}

Odezva akce kontraktu

Vrátí seznam všech akcí, které může uživatel provést za aktuálního stavu zadané instance chytrého kontraktu.

Modify: Umožňuje uživateli upravit popis a cenu majetku.
Ukončit: umožňuje uživateli ukončit kontrakt assetu.

Uživatelé získají všechny použitelné akce, pokud má uživatel přidruženou roli aplikace nebo má přidruženou roli instance chytrého kontraktu pro aktuální stav zadané instance chytrého kontraktu.

HTTP/1.1 200 OK
Content-type: application/json
{
    "nextLink": "/api/v1/contracts/1/actions?skip=2",
    "workflowFunctions": [
        {
            "id": 2,
            "name": "Modify",
            "description": "Modify the description/price attributes of this asset transfer instance",
            "displayName": "Modify",
            "parameters": [
                {
                    "id": 1,
                    "name": "description",
                    "description": "The new description of the asset",
                    "displayName": "Description",
                    "type": {
                        "id": 2,
                        "name": "string",
                        "elementType": null,
                        "elementTypeId": 0
                    }
                },
                {
                    "id": 2,
                    "name": "price",
                    "description": "The new price of the asset",
                    "displayName": "Price",
                    "type": {
                        "id": 3,
                        "name": "money",
                        "elementType": null,
                        "elementTypeId": 0
                    }
                }
            ],
            "workflowId": 1
        },
        {
            "id": 3,
            "name": "Terminate",
            "description": "Used to cancel this particular instance of asset transfer",
            "displayName": "Terminate",
            "parameters": [],
            "workflowId": 1
        }
    ]
}

Provedení akce pro kontrakt

K provedení akce pro zadanou instanci inteligentního kontraktu použijte akci post API pro akci kontraktu .

Požadavek POST akce smlouvy

V takovém případě Zvažte situaci, kdy uživatel chce změnit popis a cenu assetu.

POST /api/v1/contracts/{contractId}/actions
Authorization: Bearer {access token}
actionInformation: {
    "workflowFunctionId": 2,
    "workflowActionParameters": [
        {
            "name": "description",
            "value": "My updated car"
        },
        {
            "name": "price",
            "value": "54321"
        }
    ]
}

Uživatelé mohou provést pouze akci dostupnou pro aktuální stav zadané instance chytrého kontraktu a pro jim přidruženou roli aplikace nebo přidruženou roli instance chytrého kontraktu.

Odpověď po odeslání akce smlouvy

Pokud je požadavek úspěšný, vrátí se odpověď HTTP 200 OK bez dalších informací.

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

Další kroky

Referenční informace o rozhraních API blockchain Workbench najdete v referenčních informacích k Azure blockchain workbench REST API.

Používání Azure blockchain Workbench Preview REST API

Ohodnoťte vaše zkušenosti

Koncový bod rozhraní API pro blockchain Workbench

Authentication

S využitím Postmana

Vytvoření aplikace

Žádosti po odeslání

Aplikace po odpovědi

Požadavek POST kódu kontraktu

Odpověď po odeslání kódu kontraktu

Přiřazení rolí uživatelům

Přiřazení rolí – požadavek po odeslání

Přiřazení rolí po odpovědi

Výpis aplikací

Žádosti o získání

Aplikace obdrží odpověď.

Výpis pracovních postupů pro aplikaci

Žádost o pracovní postupy aplikace

Odpověď pracovních postupů aplikace

Vytvoření instance kontraktu

Kontrakt po požadavku

Kontrakt po odpovědi

Výpis instancí chytrých kontraktů pro pracovní postup

Žádost o smlouvy

Odpověď smluv

Výpis dostupných akcí pro kontrakt

Žádost o akci smlouvy

Odezva akce kontraktu

Provedení akce pro kontrakt

Požadavek POST akce smlouvy

Odpověď po odeslání akce smlouvy

Další kroky