Aggiornamenti dello schema per App per la logica di Azure: anteprima del 1° agosto 2015Schema updates for Azure Logic Apps - August 1, 2015 preview

La nuova versione dello schema e dell'API per App per la logica di Azure include importanti miglioramenti che rendono le app per la logica più affidabili e facili da usare:This new schema and API version for Azure Logic Apps includes key improvements that make logic apps more reliable and easier to use:

Passare alle connessioni APIMove to API connections

Il cambiamento più importante riguarda il fatto che non è più necessario distribuire app per le API nella sottoscrizione di Azure per poter usare le API.The biggest change is that you no longer have to deploy API Apps into your Azure subscription so you can use APIs. Ecco in che modo è possibile usare le API:Here are the ways that you can use APIs:

  • API gestiteManaged APIs
  • API Web personalizzateYour custom Web APIs

Ciascun metodo viene gestito in modo leggermente diverso perché prevede modelli di gestione e hosting diversi.Each way is handled slightly differently because their management and hosting models are different. Un vantaggio di questo modello è che non si è più vincolati a risorse che vengono distribuite nel gruppo di risorse di Azure.One advantage of this model is you're no longer constrained to resources that are deployed in your Azure resource group.

API gestiteManaged APIs

Microsoft gestisce alcune API per conto dell'utente, ad esempio Office 365, Salesforce, Twitter e FTP.Microsoft manages some APIs on your behalf, such as Office 365, Salesforce, Twitter, and FTP. È possibile usare alcune API gestite così come sono, ad esempio Bing Translate, mentre altre richiedono una configurazione.You can use some managed APIs as-is, such as Bing Translate, while others require configuration. Questa configurazione è detta connessione.This configuration is called a connection.

Quando si usa Office 365, ad esempio, è necessario creare una connessione contenente il token di accesso a Office 365.For example, when you use Office 365, you must create a connection that contains your Office 365 sign-in token. Il token è archiviato in modo sicuro e aggiornato in modo che l'app per la logica possa sempre chiamare l'API di Office 365.This token is securely stored and refreshed so that your logic app can always call the Office 365 API. In alternativa, per connettersi al server SQL o FTP è necessario creare una connessione che includa la stringa di connessione.Alternatively, if you want to connect to your SQL or FTP server, you must create a connection that has the connection string.

In questa definizione, queste azioni sono denominate APIConnection.In this definition, these actions are called APIConnection. Di seguito è riportato un esempio di connessione che chiama Office 365 per inviare un messaggio di posta elettronica:Here is an example of a connection that calls Office 365 to send an email:

{
    "actions": {
        "Send_Email": {
            "type": "ApiConnection",
            "inputs": {
                "host": {
                    "api": {
                        "runtimeUrl": "https://msmanaged-na.azure-apim.net/apim/office365"
                    },
                    "connection": {
                        "name": "@parameters('$connections')['shared_office365']['connectionId']"
                    }
                },
                "method": "post",
                "body": {
                    "Subject": "Reminder",
                    "Body": "Don't forget!",
                    "To": "me@contoso.com"
                },
                "path": "/Mail"
            }
        }
    }
}

L'oggetto host è la porzione di input univoca per le connessioni API e contiene due parti: api e connection.The host object is portion of inputs that is unique to API connections, and contains tow parts: api and connection.

api contiene l'URL di runtime della posizione in cui è ospitata l'API gestita.The api has the runtime URL of where that managed API is hosted. Per visualizzare tutte le API gestite disponibili, è possibile chiamare GET https://management.azure.com/subscriptions/{subid}/providers/Microsoft.Web/managedApis/?api-version=2015-08-01-preview.You can see all the available managed APIs by calling GET https://management.azure.com/subscriptions/{subid}/providers/Microsoft.Web/managedApis/?api-version=2015-08-01-preview.

Quando si usa un'API, questa può presentare o meno parametri di connessione definiti.When you use an API, the API might or might not have any connection parameters defined. Se non sono definiti, non è richiesta alcuna connessione.If the API doesn't, no connection is required. Se sono definiti, è necessario creare una connessione.If the API does, you must create a connection. La connessione creata ha il nome scelto.The created connection has the name that you choose. Poi si fa riferimento al nome nell'oggetto connection all'interno dell'oggetto host.You then reference the name in the connection object inside the host object. Per creare una connessione in un gruppo di risorse, chiamare:To create a connection in a resource group, call:

PUT https://management.azure.com/subscriptions/{subid}/resourceGroups/{rgname}/providers/Microsoft.Web/connections/{name}?api-version=2015-08-01-preview

Con il corpo seguente:With the following body:

{
  "properties": {
    "api": {
      "id": "/subscriptions/{subid}/providers/Microsoft.Web/managedApis/azureblob"
    },
    "parameterValues": {
        "accountName": "{The name of the storage account -- the set of parameters is different for each API}"
    }
  },
  "location": "{Logic app's location}"
}

Distribuire API gestite in un modello di Azure Resource ManagerDeploy managed APIs in an Azure Resource Manager template

È possibile creare un'applicazione completa in un modello di Azure Resource Manager, purché non sia necessario l'accesso interattivo.You can create a full application in an Azure Resource Manager template as long as interactive sign-in isn't required. Se è necessario l'accesso, è possibile impostare tutto con il modello di Azure Resource Manager, ma sarà comunque necessario visitare il portale per autorizzare le connessioni.If sign-in is required, you can set up everything with the Azure Resource Manager template, but you still have to visit the portal to authorize the connections.

    "resources": [{
        "apiVersion": "2015-08-01-preview",
        "name": "azureblob",
        "type": "Microsoft.Web/connections",
        "location": "[resourceGroup().location]",
        "properties": {
            "api": {
                "id": "[concat(subscription().id,'/providers/Microsoft.Web/locations/westus/managedApis/azureblob')]"
            },
            "parameterValues": {
                "accountName": "[parameters('storageAccountName')]",
                "accessKey": "[parameters('storageAccountKey')]"
            }
        }
    }, {
        "type": "Microsoft.Logic/workflows",
        "apiVersion": "2015-08-01-preview",
        "name": "[parameters('logicAppName')]",
        "location": "[resourceGroup().location]",
        "dependsOn": ["[resourceId('Microsoft.Web/connections', 'azureblob')]"
        ],
        "properties": {
            "sku": {
                "name": "[parameters('sku')]",
                "plan": {
                    "id": "[concat(resourceGroup().id, '/providers/Microsoft.Web/serverfarms/',parameters('svcPlanName'))]"
                }
            },
            "definition": {
                "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2015-08-01-preview/workflowdefinition.json#",
                "actions": {
                    "Create_file": {
                        "type": "apiconnection",
                        "inputs": {
                            "host": {
                                "api": {
                                    "runtimeUrl": "https://logic-apis-westus.azure-apim.net/apim/azureblob"
                                },
                                "connection": {
                                    "name": "@parameters('$connections')['azureblob']['connectionId']"
                                }
                            },
                            "method": "post",
                            "queries": {
                                "folderPath": "[concat('/', parameters('containerName'))]",
                                "name": "helloworld.txt"
                            },
                            "body": "@decodeDataUri('data:, Hello+world!')",
                            "path": "/datasets/default/files"
                        },
                        "conditions": []
                    }
                },
                "contentVersion": "1.0.0.0",
                "outputs": {},
                "parameters": {
                    "$connections": {
                        "defaultValue": {},
                        "type": "Object"
                    }
                },
                "triggers": {
                    "recurrence": {
                        "type": "Recurrence",
                        "recurrence": {
                            "frequency": "Day",
                            "interval": 1
                        }
                    }
                }
            },
            "parameters": {
                "$connections": {
                    "value": {
                        "azureblob": {
                            "connectionId": "[concat(resourceGroup().id,'/providers/Microsoft.Web/connections/azureblob')]",
                            "connectionName": "azureblob",
                            "id": "[concat(subscription().id,'/providers/Microsoft.Web/locations/westus/managedApis/azureblob')]"
                        }

                    }
                }
            }
        }
    }]

Come si vede in questo esempio, le connessioni non sono altro che risorse presenti nel gruppo di risorse.You can see in this example that the connections are just resources that live in your resource group. Fanno riferimento alle API gestite disponibili nella sottoscrizione dell'utente.They reference the managed APIs available to you in your subscription.

API Web personalizzateYour custom Web APIs

Se si usano API personalizzate, non quelle gestite da Microsoft, usare l'azione HTTP predefinita per chiamarle.If you use your own APIs, not Microsoft-managed ones, use the built-in HTTP action to call them. Per un'esperienza ideale, si consiglia di esporre un endpoint swagger per l'API.For an ideal experience, you should expose a Swagger endpoint for your API. Questo endpoint consente alla finestra di progettazione di app per la logica di eseguire il rendering degli input e degli output per l'API.This endpoint enables the Logic App Designer to render the inputs and outputs for your API. Senza Swagger, la finestra di progettazione può mostrare gli input e gli output solo come oggetti JSON opachi.Without Swagger, the designer can only show the inputs and outputs as opaque JSON objects.

Di seguito è riportato un esempio che mostra la nuova proprietà metadata.apiDefinitionUrl :Here is an example showing the new metadata.apiDefinitionUrl property:

{
   "actions": {
        "mycustomAPI": {
            "type": "http",
            "metadata": {
              "apiDefinitionUrl": "https://mysite.azurewebsites.net/api/apidef/"  
            },
            "inputs": {
                "uri": "https://mysite.azurewebsites.net/api/getsomedata",
                "method": "GET"
            }
        }
    }
}

Se l'API Web è ospitata in Servizio app di Azure, verrà visualizzata automaticamente nell'elenco di azioni disponibili nella finestra di progettazione.If you host your Web API on Azure App Service, your Web API automatically appears in the list of actions available in the designer. In caso contrario, è necessario incollare direttamente l'URL.If not, you have to paste in the URL directly. Per poter essere usato nella finestra di progettazione di app per la logica, l'endpoint Swagger deve essere non autenticato, anche se è possibile proteggere l'API stessa con qualsiasi metodo supportato da Swagger.The Swagger endpoint must be unauthenticated to be usable in the Logic App Designer, although you can secure the API itself with whatever methods that Swagger supports.

Chiamare le app per le API già distribuite con 2015-08-01-previewCall deployed API apps with 2015-08-01-preview

Se in precedenza è stata distribuita un'app per le API, è possibile chiamare l'app usando l'azione HTTP.If you previously deployed an API App, you can call the app with the HTTP action.

Ad esempio, se si usa Dropbox per elencare i file, la definizione della versione dello schema 2014-12-01-preview può essere simile a quanto segue:For example, if you use Dropbox to list files, your 2014-12-01-preview schema version definition might have something like:

{
    "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2014-12-01-preview/workflowdefinition.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "/subscriptions/423db32d-...-b59f14c962f1/resourcegroups/avdemo/providers/Microsoft.AppService/apiapps/dropboxconnector/token": {
            "defaultValue": "eyJ0eX...wCn90",
            "type": "String",
            "metadata": {
                "token": {
                    "name": "/subscriptions/423db32d-...-b59f14c962f1/resourcegroups/avdemo/providers/Microsoft.AppService/apiapps/dropboxconnector/token"
                }
            }
        }
    },
    "actions": {
        "dropboxconnector": {
            "type": "ApiApp",
            "inputs": {
                "apiVersion": "2015-01-14",
                "host": {
                    "id": "/subscriptions/423db32d-...-b59f14c962f1/resourcegroups/avdemo/providers/Microsoft.AppService/apiapps/dropboxconnector",
                    "gateway": "https://avdemo.azurewebsites.net"
                },
                "operation": "ListFiles",
                "parameters": {
                    "FolderPath": "/myfolder"
                },
                "authentication": {
                    "type": "Raw",
                    "scheme": "Zumo",
                    "parameter": "@parameters('/subscriptions/423db32d-...-b59f14c962f1/resourcegroups/avdemo/providers/Microsoft.AppService/apiapps/dropboxconnector/token')"
                }
            }
        }
    }
}

È possibile costruire l'azione HTTP equivalente come nell'esempio seguente, mentre la sezione parameters della definizione dell'app per la logica rimane invariata:You can construct the equivalent HTTP action like this example, while the parameters section of the Logic app definition remains unchanged:

{
    "actions": {
        "dropboxconnector": {
            "type": "Http",
            "metadata": {
              "apiDefinitionUrl": "https://avdemo.azurewebsites.net/api/service/apidef/dropboxconnector/?api-version=2015-01-14&format=swagger-2.0-standard"  
            },
            "inputs": {
                "uri": "https://avdemo.azurewebsites.net/api/service/invoke/dropboxconnector/ListFiles?api-version=2015-01-14",
                "method": "POST",
                "body": {
                    "FolderPath": "/myfolder"
                },
                "authentication": {
                    "type": "Raw",
                    "scheme": "Zumo",
                    "parameter": "@parameters('/subscriptions/423db32d-...-b59f14c962f1/resourcegroups/avdemo/providers/Microsoft.AppService/apiapps/dropboxconnector/token')"
                }
            }
        }
    }
}

La tabella seguente illustra le singole proprietà:Walking through these properties one-by-one:

Proprietà dell'azioneAction property DescrizioneDescription
type Http anziché APIappHttp instead of APIapp
metadata.apiDefinitionUrl Per usare questa azione nella finestra di progettazione di app per la logica, includere l'endpoint dei metadati, costituito da: {api app host.gateway}/api/service/apidef/{last segment of the api app host.id}/?api-version=2015-01-14&format=swagger-2.0-standardTo use this action in the Logic App Designer, include the metadata endpoint, which is constructed from: {api app host.gateway}/api/service/apidef/{last segment of the api app host.id}/?api-version=2015-01-14&format=swagger-2.0-standard
inputs.uri Costituito da: {api app host.gateway}/api/service/invoke/{last segment of the api app host.id}/{api app operation}?api-version=2015-01-14Constructed from: {api app host.gateway}/api/service/invoke/{last segment of the api app host.id}/{api app operation}?api-version=2015-01-14
inputs.method Sempre POSTAlways POST
inputs.body Identica ai parametri dell'app per le APIIdentical to the API App parameters
inputs.authentication Identica all'autenticazione dell'app per le APIIdentical to the API App authentication

Questo approccio dovrebbe funzionare per tutte le azioni delle app per le API.This approach should work for all API App actions. Tenere tuttavia presente che queste app per le api precedenti non sono più supportate.However, remember that these previous API Apps are no longer supported. È quindi consigliabile passare a una delle altre due opzioni precedenti, un'API gestita o l'hosting dell'API Web personalizzata.So you should move to one of the two other previous options, a managed API or hosting your custom Web API.

"Repeat" rinominato come "foreach"Renamed 'repeat' to 'foreach'

In base ai commenti e suggerimenti ricevuti dai clienti per la versione dello schema precedente, Ripeti generava confusione e non era chiaramente identificabile come ciclo Foreach .For the previous schema version, we received much customer feedback that Repeat was confusing and didn't properly capture that Repeat was really a for-each loop. Di conseguenza, repeat è stato rinominato in foreach.As a result, we have renamed repeat to foreach. Ad esempio, in precedenza si sarebbe scritto:For example, previously you would write:

{
    "actions": {
        "pingBing": {
            "type": "Http",
            "repeat": "@range(0,2)",
            "inputs": {
                "method": "GET",
                "uri": "https://www.bing.com/search?q=@{repeatItem()}"
            }
        }
    }
}

Ora si scriverebbe:Now you would write:

{
    "actions": {
        "pingBing": {
            "type": "Http",
            "foreach": "@range(0,2)",
            "inputs": {
                "method": "GET",
                "uri": "https://www.bing.com/search?q=@{item()}"
            }
        }
    }
}

In precedenza veniva usata la funzione @repeatItem() per fare riferimento all'elemento corrente sottoposto a iterazione.The function @repeatItem() was previously used to reference the current item being iterated over. Questa funzione è ora semplificata a @item().This function is now simplified to @item().

Fare riferimento agli output da "foreach"Reference outputs from 'foreach'

Per maggiore semplicità, non viene eseguito il wrapping degli output dalle azioni foreach in un oggetto denominato repeatItems.For simplification, the outputs from foreach actions are not wrapped in an object called repeatItems. Mentre gli output dall'esempio di repeat precedente erano:While the outputs from the previous repeat example were:

{
    "repeatItems": [
        {
            "name": "pingBing",
            "inputs": {
                "uri": "https://www.bing.com/search?q=0",
                "method": "GET"
            },
            "outputs": {
                "headers": { },
                "body": "<!DOCTYPE html><html lang=\"en\" xml:lang=\"en\" xmlns=\"http://www.w3.org/1999/xhtml\" xmlns:Web=\"http://schemas.live.com/Web/\">...</html>"
            }
            "status": "Succeeded"
        }
    ]
}

Ora tali output sono:Now these outputs are:

[
    {
        "name": "pingBing",
        "inputs": {
            "uri": "https://www.bing.com/search?q=0",
            "method": "GET"
        },
        "outputs": {
            "headers": { },
            "body": "<!DOCTYPE html><html lang=\"en\" xml:lang=\"en\" xmlns=\"http://www.w3.org/1999/xhtml\" xmlns:Web=\"http://schemas.live.com/Web/\">...</html>"
        }
        "status": "Succeeded"
    }
]

Prima per ottenere il corpo dell'azione facendo riferimento agli output, era necessario eseguire:Previously, to get to the body of the action when referencing these outputs:

{
    "actions": {
        "secondAction": {
            "type": "Http",
            "repeat": "@outputs('pingBing').repeatItems",
            "inputs": {
                "method": "POST",
                "uri": "http://www.example.com",
                "body": "@repeatItem().outputs.body"
            }
        }
    }
}

Ora, invece, è possibile eseguire:Now you can do instead:

{
    "actions": {
        "secondAction": {
            "type": "Http",
            "foreach": "@outputs('pingBing')",
            "inputs": {
                "method": "POST",
                "uri": "http://www.example.com",
                "body": "@item().outputs.body"
            }
        }
    }
}

Con queste modifiche, le funzioni @repeatItem(), @repeatBody() e @repeatOutputs() sono state rimosse.With these changes, the functions @repeatItem(), @repeatBody(), and @repeatOutputs() are removed.

Listener HTTP nativoNative HTTP listener

Le funzionalità del listener HTTP ora sono predefinite.The HTTP Listener capabilities are now built in. Non è quindi più necessario distribuire un'app per le API del listener HTTP.So you no longer need to deploy an HTTP Listener API App. Per informazioni dettagliate, vedere App per la logica come endpoint che è possibile chiamare.See the full details for how to make your Logic app endpoint callable here.

Con queste modifiche, è stata rimossa la funzione @accessKeys(), che è stata sostituita con la funzione @listCallbackURL() per ottenere l'endpoint, se necessario.With these changes, we removed the @accessKeys() function, which we replaced with the @listCallbackURL() function for getting the endpoint when necessary. Ora è anche necessario definire almeno un trigger nell'app per la logica.Also, you must now define at least one trigger in your logic app. Per eseguire il comando /run sul flusso di lavoro, è necessario avere un trigger manual, apiConnectionWebhook o httpWebhook.If you want to /run the workflow, you must have one of these triggers: manual, apiConnectionWebhook, or httpWebhook.

Chiamare flussi di lavoro figlioCall child workflows

In precedenza, per la chiamata a flussi di lavoro figlio era necessario passare al flusso di lavoro, ottenere il token di accesso e incollare il token nella definizione dell'app per la logica in cui si vuole chiamare tale flusso di lavoro figlio.Previously, calling child workflows required going to the workflow, getting the access token, and pasting the token in the logic app definition where you want to call that child workflow. Con il nuovo schema, il motore di app per la logica genera automaticamente una firma di accesso condiviso in fase di esecuzione per il flusso di lavoro figlio, quindi non è necessario incollare segreti nella definizione.With the new schema, the Logic Apps engine automatically generates a SAS at runtime for the child workflow so you don't have to paste any secrets into the definition. Di seguito è fornito un esempio:Here is an example:

"mynestedwf": {
    "type": "workflow",
    "inputs": {
        "host": {
            "id": "/subscriptions/xxxxyyyyzzz/resourceGroups/rg001/providers/Microsoft.Logic/mywf001",
            "triggerName": "myendpointtrigger"
        },
        "queries": {
            "extrafield": "specialValue"
        },
        "headers": {
            "x-ms-date": "@utcnow()",
            "Content-type": "application/json"
        },
        "body": {
            "contentFieldOne": "value100",
            "anotherField": 10.001
        }
    },
    "conditions": []
}

Un secondo miglioramento è l'accesso completo alla richiesta in ingresso per i flussi di lavoro figlio.A second improvement is we are giving the child workflows full access to the incoming request. Ciò significa che è possibile passare parametri nella sezione queries e nell'oggetto headers e che è possibile definire completamente l'intero corpo.That means that you can pass parameters in the queries section and in the headers object and that you can fully define the entire body.

Infine, è stato necessario apportare modifiche al flusso di lavoro figlio.Finally, there are required changes to the child workflow. Mentre in precedenza era possibile chiamare direttamente un flusso di lavoro figlio, ora occorre definire un endpoint trigger nel flusso di lavoro che l'elemento padre possa chiamare.While you could previously call a child workflow directly, now you must define a trigger endpoint in the workflow for the parent to call. In genere, si aggiungerà un trigger con il tipo manual da usare nella definizione dell'elemento padre.Generally, you would add a trigger that has manual type, and then use that trigger in the parent definition. Si noti che la proprietà host in particolare include un triggerName, perché è sempre necessario specificare quale trigger viene richiamato.Note the host property specifically has a triggerName because you must always specify which trigger you are invoking.

Altre modificheOther changes

Nuova proprietà "queries"New 'queries' property

Tutti i tipi di azione ora supportano un nuovo input denominato queries.All action types now support a new input called queries. Questo input può essere un oggetto strutturato e non è più necessario assemblare la stringa manualmente.This input can be a structured object, rather than you having to assemble the string by hand.

Funzione "parse()" rinominata come "json()"Renamed 'parse()' function to 'json()'

Verranno aggiunti a breve altri tipi di contenuti, quindi la funzione parse() è stata rinominata json().We are adding more content types soon, so we renamed the parse() function to json().

Presto disponibile: API Enterprise IntegrationComing soon: Enterprise Integration APIs

Non sono ancora disponibili versioni gestite delle API Enterprise Integration, ad esempio AS2.We don't have managed versions yet of the Enterprise Integration APIs, like AS2. Per il momento è possibile usare le API di BizTalk distribuite tramite l'azione HTTP.Meanwhile, you can use your existing deployed BizTalk APIs through the HTTP action. Per informazioni dettagliate, vedere "Using your already deployed API apps" (Uso delle app per le API già distribuite) nella guida di orientamento all'integrazione.For details, see "Using your already deployed API apps" in the integration roadmap.