Integración de los mensajes de Azure Blockchain Workbench

Además de proporcionar una API REST, Azure Blockchain Workbench proporciona integración basada en mensajería. Workbench publica eventos centrados en el libro de contabilidad a través de Azure Event Grid, lo que permite a los consumidores de nivel final ingerir datos o realizar acciones en función de estos eventos. Para aquellos clientes que precisan de mensajería de confianza, Azure Blockchain Workbench también entrega mensajes a un punto de conexión de Azure Service Bus.

API de entrada

Si quiere iniciar las transacciones desde sistemas externos para crear usuarios, crear contratos y actualizar contratos, puede usar las API de entrada de mensajería para realizar transacciones en un libro de contabilidad. Consulte los ejemplos de integración de mensajería para obtener ejemplos que muestren las API de entrada.

Las siguientes son las API de entrada actualmente disponibles.

Crear usuario

Crea un nuevo usuario.

La solicitud requiere los siguientes campos:

Ejemplo:

{
    "requestId": "e2264523-6147-41fc-bbbb-edba8e44562d",
    "firstName": "Ali",
    "lastName": "Alio",
    "emailAddress": "aa@contoso.com",
    "externalId": "6a9b7f65-ffff-442f-b3b8-58a35abd1bcd",
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "CreateUserRequest"
}

Blockchain Workbench devuelve una respuesta con los siguientes campos:

Ejemplo de una respuesta correcta de creación de usuario desde Blockchain Workbench:

{ 
    "requestId": "e2264523-6147-41fc-bb59-edba8e44562d", 
    "userId": 15, 
    "userChainIdentifier": "0x9a8DDaCa9B7488683A4d62d0817E965E8f248398", 
    "connectionId": 1, 
    "messageSchemaVersion": "1.0.0", 
    "messageName": "CreateUserUpdate", 
    "status": "Success", 
    "additionalInformation": { } 
} 

Si la solicitud no se realizó correctamente, se incluyen detalles sobre el error en la información adicional.

{
    "requestId": "e2264523-6147-41fc-bb59-edba8e44562d", 
    "userId": 15, 
    "userChainIdentifier": null, 
    "connectionId": 1, 
    "messageSchemaVersion": "1.0.0", 
    "messageName": "CreateUserUpdate", 
    "status": "Failure", 
    "additionalInformation": { 
        "errorCode": 4000, 
        "errorMessage": "User cannot be provisioned on connection." 
    }
}

Crear contrato

Crea un nuevo contrato.

La solicitud requiere los siguientes campos:

Ejemplo:

{ 
    "requestId": "ce3c429b-a091-4baa-b29b-5b576162b211", 
    "userChainIdentifier": "0x9a8DDaCa9B7488683A4d62d0817E965E8f248398", 
    "applicationName": "AssetTransfer",
    "version": "1.0",
    "workflowName": "AssetTransfer", 
    "parameters": [ 
        { 
            "name": "description", 
            "value": "a 1969 dodge charger" 
        }, 
        { 
            "name": "price", 
            "value": "12345" 
        } 
    ], 
    "connectionId": 1, 
    "messageSchemaVersion": "1.0.0", 
    "messageName": "CreateContractRequest" 
}

Blockchain Workbench devuelve una respuesta con los siguientes campos:

Ejemplo de una respuesta de crear contrato enviada desde Blockchain Workbench:

{
    "requestId": "ce3c429b-a091-4baa-b29b-5b576162b211",
    "contractId": 55,
    "contractLedgerIdentifier": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "CreateContractUpdate",
    "status": "Submitted",
    "additionalInformation": { }
}

Ejemplo de una respuesta de crear contrato confirmada desde Blockchain Workbench:

{
    "requestId": "ce3c429b-a091-4baa-b29b-5b576162b211",
    "contractId": 55,
    "contractLedgerIdentifier": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "CreateContractUpdate",
    "status": "Committed",
    "additionalInformation": { }
}

Si la solicitud no se realizó correctamente, se incluyen detalles sobre el error en la información adicional.

{
    "requestId": "ce3c429b-a091-4baa-b29b-5b576162b211",
    "contractId": 55,
    "contractLedgerIdentifier": null,
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "CreateContractUpdate",
    "status": "Failure",
    "additionalInformation": {
        "errorCode": 4000,
        "errorMessage": "Contract cannot be provisioned on connection."
    }
}

Crear acción de contrato

Crea una nueva acción de contrato.

La solicitud requiere los siguientes campos:

Ejemplo:

{
    "requestId": "a5530932-9d6b-4eed-8623-441a647741d3",
    "userChainIdentifier": "0x9a8DDaCa9B7488683A4d62d0817E965E8f248398",
    "contractLedgerIdentifier": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
    "version": "1.0",
    "workflowFunctionName": "modify",
    "parameters": [
        {
            "name": "description",
            "value": "a 1969 dodge charger"
        },
        {
            "name": "price",
            "value": "12345"
        }
    ],
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "CreateContractActionRequest"
}

Blockchain Workbench devuelve una respuesta con los siguientes campos:

Ejemplo de una respuesta de crear acción de contrato enviada desde Blockchain Workbench:

{
    "requestId": "a5530932-9d6b-4eed-8623-441a647741d3",
    "contractId": 105,
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "CreateContractActionUpdate",
    "status": "Submitted",
    "additionalInformation": { }
}

Ejemplo de una respuesta de crear acción de contrato confirmada desde Blockchain Workbench:

{
    "requestId": "a5530932-9d6b-4eed-8623-441a647741d3",
    "contractId": 105,
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "CreateContractActionUpdate",
    "status": "Committed",
    "additionalInformation": { }
}

Si la solicitud no se realizó correctamente, se incluyen detalles sobre el error en la información adicional.

{
    "requestId": "a5530932-9d6b-4eed-8623-441a647741d3",
    "contractId": 105,
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "CreateContractActionUpdate",
    "status": "Failure",
    "additionalInformation": {
        "errorCode": 4000,
        "errorMessage": "Contract action cannot be provisioned on connection."
    }
}

Mensajes y códigos de error de la API de entrada

Código de error 4000: Error de solicitud incorrecta

• ConnectionId no válido
• Error de deserialización de CreateUserRequest
• Error de deserialización de CreateContractRequest
• Error de deserialización de CreateContractActionRequest
• La aplicación {identificada por el nombre de la aplicación} no existe.
• La aplicación {identificada por el nombre de la aplicación} no tiene ningún flujo de trabajo.
• UserChainIdentifier no existe.
• El contrato {identificado por el identificador del libro de contabilidad} no existe.
• El contrato {identificado por el identificador del libro de contabilidad} no tiene la función {nombre de la función del flujo de trabajo}.
• UserChainIdentifier no existe.

Código de error 4090: Error de conflicto

• El usuario ya existe.
• El contrato ya existe.
• La acción de contrato ya existe.

Código de error 5000: Error interno del servidor

• Mensajes de excepción

Notificaciones de eventos

Las notificaciones de eventos se pueden usar para notificar a los usuarios y a los sistemas de nivel final de eventos que se producen en Blockchain Workbench y la red de cadena de bloques a la que está conectada. Las notificaciones de eventos se pueden consumir directamente en código o se pueden utilizar con herramientas como Logic Apps y Flow para desencadenar el flujo de datos hacia los sistemas de nivel final.

Consulte la Referencia de mensajes de notificación para más detalles sobre los distintos mensajes que se pueden recibir.

Consumo de eventos de Event Grid con Azure Functions

Si un usuario desea usar Event Grid para recibir notificaciones sobre eventos que se producen en Blockchain Workbench, puede consumir eventos de Event Grid mediante el uso de Azure Functions.

1. Cree una aplicación de función de Azure en Azure Portal.
2. Cree una nueva función.
3. Busque la plantilla de Event Grid. Se muestra el código de la plantilla básica para leer el mensaje. Modifique el código según sea necesario.
4. Guarde la función.
5. Seleccione la instancia de Event Grid desde el grupo de recursos de Blockchain Workbench.

Consumo de eventos de Event Grid con Logic Apps

1. Cree una nueva aplicación lógica de Azure en Azure Portal.
2. Al abrir la aplicación de la lógica de Azure en el portal, se le pedirá seleccionar un desencadenador. Seleccione Azure Event Grid: cuando se produce un evento de recurso.
3. Cuando se muestra el diseñador de flujo de trabajo, se le pedirá que inicie sesión.
4. Seleccione la suscripción. Recurso como Microsoft.EventGrid.Topics. Seleccione el Nombre de recurso desde el nombre del recurso del grupo de recursos de Azure Blockchain Workbench.
5. Seleccione la instancia de Event Grid desde el grupo de recursos de Blockchain Workbench.

Uso de temas de Service Bus para notificaciones

Los temas de Service Bus se pueden utilizar para notificar a los usuarios acerca de los eventos que se producen en Blockchain Workbench.

1. Vaya a Service Bus en el grupo de recursos de Workbench.
2. Seleccione Temas.
3. Seleccione egress-topic.
4. Cree una nueva suscripción a este tema. Obtenga una clave para la suscripción.
5. Cree un programa, que se suscribe a los eventos de esta suscripción.

Consumo de mensajes de Service Bus con Logic Apps

1. Cree una nueva aplicación lógica de Azure en Azure Portal.
2. Al abrir la aplicación de la lógica de Azure en el portal, se le pedirá seleccionar un desencadenador. Escriba Service Bus en el cuadro de búsqueda y seleccione el desencadenador adecuado para el tipo de interacción que desea tener con Service Bus. Por ejemplo, Service Bus: cuando se recibe un mensaje en una suscripción de tema (autocompletar) .
3. Cuando se muestra el diseñador de flujo de trabajo, especifique la información de conexión para Service Bus.
4. Seleccione la suscripción y especifique el tema workbench-external.
5. Desarrolle la lógica de la aplicación que utiliza el mensaje de este desencadenador.

Referencia de mensajes de notificación

En función del valor de messageName, los mensajes de notificación tienen uno de los siguientes tipos de mensaje.

Mensaje de bloque

Contiene información sobre bloques individuales. BlockMessage incluye una sección con información de nivel de bloque y una sección con información de la transacción.

Información de bloque

Información de la transacción

Ejemplo de un BlockMessage de Blockchain Workbench:

{
    "block": {
        "blockId": 123,
        "blockNumber": 1738312,
        "blockHash": "0x03a39411e25e25b47d0ec6433b73b488554a4a5f6b1a253e0ac8a200d13fffff",
        "previousBlockHash": null,
        "blockTimestamp": "2018-10-09T23:35:58Z",
    },
    "transactions": [
        {
            "transactionId": 234,
            "transactionHash": "0xa4d9c95b581f299e41b8cc193dd742ef5a1d3a4ddf97bd11b80d123fec27ffff",
            "from": "0xd85e7262dd96f3b8a48a8aaf3dcdda90f60dffff",
            "to": null,
            "provisioningStatus": 1
        },
        {
            "transactionId": 235,
            "transactionHash": "0x5c1fddea83bf19d719e52a935ec8620437a0a6bdaa00ecb7c3d852cf92e1ffff",
            "from": "0xadd97e1e595916e29ea94fda894941574000ffff",
            "to": "0x9a8DDaCa9B7488683A4d62d0817E965E8f24ffff",
            "provisioningStatus": 2
        }
    ],
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "BlockMessage",
    "additionalInformation": {}
}

Mensaje del contrato

Contiene información sobre un contrato. El mensaje incluye una sección con propiedades del contrato y una sección con información de la transacción. Todas las transacciones que han modificado el contrato para el bloque determinado se incluyen en la sección de la transacción.

Modificación de la información de la transacción

Propiedades del contrato

Ejemplo de un ContractMessage de Blockchain Workbench:

{
    "blockId": 123,
    "blockhash": "0x03a39411e25e25b47d0ec6433b73b488554a4a5f6b1a253e0ac8a200d13fffff",
    "modifyingTransactions": [
        {
            "transactionId": 234,
            "transactionHash": "0x5c1fddea83bf19d719e52a935ec8620437a0a6bdaa00ecb7c3d852cf92e1ffff",
            "from": "0xd85e7262dd96f3b8a48a8aaf3dcdda90f60dffff",
            "to": "0xf8559473b3c7197d59212b401f5a9f07ffff"
        },
        {
            "transactionId": 235,
            "transactionHash": "0xa4d9c95b581f299e41b8cc193dd742ef5a1d3a4ddf97bd11b80d123fec27ffff",
            "from": "0xd85e7262dd96f3b8a48a8aaf3dcdda90f60dffff",
            "to": "0xf8559473b3c7197d59212b401f5a9f07b429ffff"
        }
    ],
    "contractId": 111,
    "contractLedgerIdentifier": "0xf8559473b3c7197d59212b401f5a9f07b429ffff",
    "contractProperties": [
        {
            "workflowPropertyId": 1,
            "name": "State",
            "value": "0"
        },
        {
            "workflowPropertyId": 2,
            "name": "Description",
            "value": "1969 Dodge Charger"
        },
        {
            "workflowPropertyId": 3,
            "name": "AskingPrice",
            "value": "30000"
        },
        {
            "workflowPropertyId": 4,
            "name": "OfferPrice",
            "value": "0"
        },
        {
            "workflowPropertyId": 5,
            "name": "InstanceAppraiser",
            "value": "0x0000000000000000000000000000000000000000"
        },
        {
            "workflowPropertyId": 6,
            "name": "InstanceBuyer",
            "value": "0x0000000000000000000000000000000000000000"
        },
        {
            "workflowPropertyId": 7,
            "name": "InstanceInspector",
            "value": "0x0000000000000000000000000000000000000000"
        },
        {
            "workflowPropertyId": 8,
            "name": "InstanceOwner",
            "value": "0x9a8DDaCa9B7488683A4d62d0817E965E8f24ffff"
        },
        {
            "workflowPropertyId": 9,
            "name": "ClosingDayOptions",
            "value": "[21,48,69]"
        }
    ],
    "isNewContract": false,
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "ContractMessage",
    "additionalInformation": {}
}

Mensaje de evento: Invocación de la función de contrato

Contiene información cuando se invoca una función de contrato, por ejemplo, el nombre de función, la entradas de parámetros y el llamador de la función.

Información del autor de la llamada

Información del parámetro

Información de la transacción del mensaje de eventos

Ejemplo de EventMessage ContractFunctionInvocation de Blockchain Workbench:

{
    "eventName": "ContractFunctionInvocation",
    "caller": {
        "type": "User",
        "id": 21,
        "ledgerIdentifier": "0xd85e7262dd96f3b8a48a8aaf3dcdda90f60ffff"
    },
    "contractId": 34,
    "contractLedgerIdentifier": "0xf8559473b3c7197d59212b401f5a9f07b429ffff",
    "functionName": "Modify",
    "parameters": [
        {
            "name": "description",
            "value": "a new description"
        },
        {
            "name": "price",
            "value": "4567"
        }
    ],
    "transaction": {
        "transactionId": 234,
        "transactionHash": "0x5c1fddea83bf19d719e52a935ec8620437a0a6bdaa00ecb7c3d852cf92e1ffff",
        "from": "0xd85e7262dd96f3b8a48a8aaf3dcdda90f60dffff",
        "to": "0xf8559473b3c7197d59212b401f5a9f07b429ffff"
    },
    "inTransactionSequenceNumber": 1,
    "connectionId": 1,
    "messageSchemaVersion": "1.0.0",
    "messageName": "EventMessage",
    "additionalInformation": { }
}

Mensaje de evento: Ingesta de aplicación

Contiene información de cuando una aplicación se carga en Workbench, como el nombre y la versión de la aplicación cargada.

Información de código de contrato

Información de rol de la aplicación

Información del flujo de trabajo de la aplicación

Información de la función del flujo de trabajo

Información de estado de flujo de trabajo

Información de la propiedad del flujo de trabajo

Ejemplo de EventMessage ApplicationIngestion de Blockchain Workbench:

{
    "eventName": "ApplicationIngestion",
    "applicationId": 31,
    "applicationName": "AssetTransfer",
    "applicationDisplayName": "Asset Transfer",
    "applicationVersion": "1.0",
    "applicationDefinitionLocation": "http://url",
    "contractCodes": [
        {
            "id": 23,
            "ledgerId": 1,
            "location": "http://url"
        }
    ],
    "applicationRoles": [
            {
                "id": 134,
                "name": "Buyer"
            },
            {
                "id": 135,
                "name": "Seller"
            }
       ],
    "applicationWorkflows": [
        {
            "id": 89,
            "name": "AssetTransfer",
            "displayName": "Asset Transfer",
            "functions": [
                {
                    "id": 912,
                    "name": "",
                    "parameters": [
                        {
                            "name": "description",
                            "type": {
                                "name": "string"
                             }
                        },
                        {
                            "name": "price",
                            "type": {
                                "name": "int"
                            }
                        }
                    ]
                },
                {
                    "id": 913,
                    "name": "modify",
                    "parameters": [
                        {
                            "name": "description",
                            "type": {
                                "name": "string"
                             }
                        },
                        {
                            "name": "price",
                            "type": {
                                "name": "int"
                            }
                        }
                    ]
                }
            ],
            "states": [ 
                 {
                      "name": "Created",
                      "displayName": "Created",
                      "style" : "Success"
                 },
                 {
                      "name": "Terminated",
                      "displayName": "Terminated",
                      "style" : "Failure"
                 }
            ],
            "properties": [
                {
                    "id": 879,
                    "name": "Description",
                    "type": {
                        "name": "string"
                     }
                },
                {
                    "id": 880,
                    "name": "Price",
                    "type": {
                        "name": "int"
                     }
                }
            ]
        }
    ],
    "connectionId": [ ],
    "messageSchemaVersion": "1.0.0",
    "messageName": "EventMessage",
    "additionalInformation":
        {
            "states" :
            [
                {
                    "Name": "BuyerAccepted",
                    "Transitions": [
                        {
                            "DisplayName": "Accept",
                            "AllowedRoles": [ ],
                            "AllowedInstanceRoles": [ "InstanceOwner" ],
                            "Function": "Accept",
                            "NextStates": [ "SellerAccepted" ]
                        }
                    ]
                }
            ]
        }
}

Mensaje de evento: Asignación de roles

Contiene información de cuando a un usuario se le asigna un rol en Workbench, como quién realizó la asignación del rol y el nombre del rol y la aplicación correspondiente.

Rol de aplicación RoleAssignment

Asignador de RoleAssignment

Asignado de RoleAssignment

Ejemplo de EventMessage RoleAssignment de Blockchain Workbench:

{
    "eventName": "RoleAssignment",
    "applicationId": 31,
    "applicationName": "AssetTransfer",
    "applicationDisplayName": "Asset Transfer",
    "applicationVersion": "1.0",
    "applicationRole": {
        "id": 134,
        "name": "Buyer"
    },
    "assigner": {
        "id": 1,
        "type": null,
        "chainIdentifier": "0xeFFC7766d38aC862d79706c3C5CEEf089564ffff"
    },
    "assignee": {
        "id": 3,
        "type": null,
        "chainIdentifier": "0x9a8DDaCa9B7488683A4d62d0817E965E8f24ffff"
    },
    "connectionId": [ ],
    "messageSchemaVersion": "1.0.0",
    "messageName": "EventMessage",
    "additionalInformation": { }
}

Pasos siguientes

• Patrones de integración de contratos inteligentes