使用 API 实现 IoT Edge 流分析的 CI/CD

项目
06/02/2023

可使用 REST API 启用 Azure 流分析作业的持续集成和部署管道。本文举例说明该使用哪些 API 及其具体用法。

从不同环境调用 API

可从 Linux 和 Windows 调用 REST API。以下命令演示了调用 API 的正确语法。本文稍后会介绍特定 API 的用法。

Linux

对于 Linux，可使用 Curl 或 Wget 命令：

curl -u { <username:password> }  -H "Content-Type: application/json" -X { <method> } -d "{ <request body> }" { <url> }

wget -q -O- --{ <method> } -data="<request body>" --header=Content-Type:application/json --auth-no-challenge --http-user="<Admin>" --http-password="<password>" <url>

Windows

对于 Windows，请使用 PowerShell：

$user = "<username>" 
$pass = "<password>" 
$encodedCreds = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $user,$pass))) 
$basicAuthValue = "Basic $encodedCreds" 
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]" 
$headers.Add("Content-Type", 'application/json') 
$headers.Add("Authorization", $basicAuthValue) 
$content = "<request body>" 
$response = Invoke-RestMethod <url> -Method <method> -Body $content -Headers $Headers 
echo $response

在 IoT Edge 上创建 ASA 作业

要创建流分析作业，请使用流分析 API 调用 PUT 方法。

方法	请求 URL
PUT	`https://management.chinacloudapi.cn/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.StreamAnalytics/streamingjobs/{job-name}?api-version=2017-04-01-preview`

使用 curl 的命令示例：

curl -u { <username:password> } -H "Content-Type: application/json" -X { <method> } -d "{ <request body> }" https://management.chinacloudapi.cn/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.StreamAnalytics/streamingjobs/{jobname}?api-version=2017-04-01-preview

JSON 中的请求正文示例：

{ 
  "location": "China North", 
  "tags": { "key": "value", "ms-suppressjobstatusmetrics": "true" }, 
  "sku": {  
      "name": "Standard" 
    }, 
  "properties": { 
    "sku": {  
      "name": "standard" 
    }, 
       "eventsLateArrivalMaxDelayInSeconds": 1, 
       "jobType": "edge", 
    "inputs": [ 
      { 
        "name": "{inputname}", 
        "properties": { 
         "type": "stream", 
          "serialization": { 
            "type": "JSON", 
            "properties": { 
              "fieldDelimiter": ",", 
              "encoding": "UTF8" 
            } 
          }, 
          "datasource": { 
            "type": "GatewayMessageBus", 
            "properties": { 
            } 
          } 
        } 
      } 
    ], 
    "transformation": { 
      "name": "{queryName}", 
      "properties": { 
        "query": "{query}" 
      } 
    }, 
    "package": { 
      "storageAccount" : { 
        "accountName": "{blobstorageaccountname}", 
        "accountKey": "{blobstorageaccountkey}" 
      }, 
      "container": "{blobcontaine}]" 
    }, 
    "outputs": [ 
      { 
        "name": "{outputname}", 
        "properties": { 
          "serialization": { 
            "type": "JSON", 
            "properties": { 
              "fieldDelimiter": ",", 
              "encoding": "UTF8" 
            } 
          }, 
          "datasource": { 
            "type": "GatewayMessageBus", 
            "properties": { 
            } 
          } 
        } 
      } 
    ] 
  } 
}

有关详细信息，请参阅 API 文档。

发布 IoT Edge 程序包

要在 IoT Edge 上发布流分析作业，请使用 IoT Edge 程序包发布 API 调用 POST 方法。

方法	请求 URL
POST	`https://management.chinacloudapi.cn/subscriptions/{subscriptionid}/resourceGroups/{resourcegroupname}/providers/Microsoft.StreamAnalytics/streamingjobs/{jobname}/publishedgepackage?api-version=2017-04-01-preview`

对 IoT Edge 程序包发布 API 的上一次调用会触发异步操作，并返回 202 状态。 location 响应标头包含用于获取该异步操作的状态的 URI。对 location 标头中的 URI 的调用会返回 202 状态，指示异步操作仍在进行中。操作完成后，对 location 标头中的 URI 的调用会返回 200 状态。

使用 curl 的 IoT Edge 程序包发布调用的示例：

curl -d -X POST https://management.chinacloudapi.cn/subscriptions/{subscriptionid}/resourceGroups/{resourcegroupname}/providers/Microsoft.StreamAnalytics/streamingjobs/{jobname}/publishedgepackage?api-version=2017-04-01-preview

调用 POST 后，应得到一个正文为空的响应。查找响应的 location 标头中的 URI，并予以记录，供将来使用。

响应的 location 标头中的 URI 的示例：

https://management.chinacloudapi.cn/subscriptions/{subscriptionid}/resourcegroups/{resourcegroupname}/providers/Microsoft.StreamAnalytics/StreamingJobs/{resourcename}/OperationResults/{guidAssignedToTheAsynchronousOperation}?api-version=2017-04-01-preview

等待几秒钟到几分钟，然后调用特定的 API（你已在 IoT Edge 程序包发布 API 响应的 location 标头中找到其 URI），重复进行等待和重试，直到收到 200 响应。

使用 curl 通过返回的 URL 调用 API 的示例：

curl -d -X GET https://management.chinacloudapi.cn/subscriptions/{subscriptionid}/resourcegroups/{resourcegroupname}/providers/Microsoft.StreamAnalytics/StreamingJobs/{resourcename}/OperationResults/{guidAssignedToTheAsynchronousOperation}?api-version=2017-04-01-preview

响应中包括需添加到 IoT Edge 部署脚本的信息。以下示例显示了需收集的信息，以及要在部署清单中添加信息的位置。

成功发布后的响应正文示例：

{ 
  edgePackageUrl : null 
  error : null 
  manifest : "{"supportedPlatforms":[{"os":"linux","arch":"amd64","features":[]},{"os":"linux","arch":"arm","features":[]},{"os":"windows","arch":"amd64","features":[]}],"schemaVersion":"2","name":"{jobname}","version":"1.0.0.0","type":"docker","settings":{"image":"{imageurl}","createOptions":null},"endpoints":{"inputs":["\],"outputs":["{outputnames}"]},"twin":{"contentType":"assignments","content":{"properties.desired":{"ASAJobInfo":"{asajobsasurl}","ASAJobResourceId":"{asajobresourceid}","ASAJobEtag":"{etag}","PublishTimeStamp":"{publishtimestamp}"}}}}" 
  status : "Succeeded" 
}

部署清单示例：

{ 
  "modulesContent": { 
    "$edgeAgent": { 
      "properties.desired": { 
        "schemaVersion": "1.0", 
        "runtime": { 
          "type": "docker", 
          "settings": { 
            "minDockerVersion": "v1.25", 
            "loggingOptions": "", 
            "registryCredentials": {} 
          } 
        }, 
        "systemModules": { 
          "edgeAgent": { 
            "type": "docker", 
            "settings": { 
              "image": "mcr.microsoft.com/azureiotedge-agent:1.0", 
              "createOptions": "{}" 
            } 
          }, 
          "edgeHub": { 
            "type": "docker", 
            "status": "running", 
            "restartPolicy": "always", 
            "settings": { 
              "image": "mcr.microsoft.com/azureiotedge-hub:1.0", 
              "createOptions": "{}" 
            } 
          } 
        }, 
        "modules": { 
          "<asajobname>": { 
            "version": "1.0", 
            "type": "docker", 
            "status": "running", 
            "restartPolicy": "always", 
            "settings": { 
              "image": "<settings.image>", 
              "createOptions": "<settings.createOptions>" 
            } 
            "version": "<version>", 
             "env": { 
              "PlanId": { 
               "value": "stream-analytics-on-iot-edge" 
          } 
        } 
      } 
    }, 
    "$edgeHub": { 
      "properties.desired": { 
        "schemaVersion": "1.0", 
        "routes": { 
            "route": "FROM /* INTO $upstream" 
        }, 
        "storeAndForwardConfiguration": { 
          "timeToLiveSecs": 7200 
        } 
      } 
    }, 
    "<asajobname>": { 
      "properties.desired": {<twin.content.properties.desired>} 
    } 
  } 
}

配置部署清单后，请参阅使用 Azure CLI 部署 Azure IoT Edge 模块，了解有关部署的信息。

通过