Adicionar blobs a objetos nos Gêmeos Digitais do Azure
Importante
Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz dos recursos expandidos do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.
Para exibir a documentação do novo serviço, visite a documentação ativa dos Gêmeos Digitais do Azure.
Os blobs são representações não estruturadas de tipos de arquivos comuns, como imagens e logs. Os blobs rastreiam o tipo de dados que eles representam usando um tipo MIME (por exemplo: "image/jpeg") e metadados (nome, descrição, tipo, etc.).
Os Gêmeos Digitais do Azure oferecem suporte à conexão de blobs a dispositivos, espaços e usuários. Os blobs podem representar uma foto de perfil para um usuário, uma foto do dispositivo, um vídeo, um mapa, um zip de firmware, dados JSON, um log etc.
Este artigo pressupõe alguma familiaridade com a autenticação em suas APIs de Gerenciamento dos Gêmeos Digitais do Azure.
- Para saber mais sobre como autenticar com suas APIs de Gerenciamento, leia Autenticando com APIs dos Gêmeos Digitais do Azure.
- Para autenticar com as APIs de Gerenciamento usando o cliente Postman REST, leia Como configurar Postman.
Visão geral do upload de blobs
Você pode usar solicitações multipartes para fazer o upload de blobs para pontos de extremidade específicos e suas respectivas funcionalidades.
Observação
Normalmente, solicitações com várias partes requerem três partes:
- Um cabeçalho Content-Type :
application/json; charset=utf-8multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
- Uma disposição de conteúdo:
form-data; name="metadata"
- O conteúdo do arquivo que será carregado
Content-Type e Content-Disposition variam dependendo do cenário de uso.
Solicitações com várias partes podem ser feitas de forma programática (usando C#), por meio de um cliente REST ou de uma ferramenta como Postman. Ferramentas de cliente REST podem ter diferentes níveis de suporte para solicitações com várias partes complexas. As definições de configuração também podem variar ligeiramente de uma ferramenta para outra. Verifique qual ferramenta é mais adequada às suas necessidades.
Importante
As solicitações com várias partes feitas para as APIs de Gerenciamento dos Gêmeos Digitais do Azure normalmente são divididas em duas partes:
- metadados de blob (como um tipo MIME associado), declarados por Content-Type e/ou Content-Disposition
- Conteúdo do blob, que inclui o conteúdo não estruturado de um arquivo a ser carregado
Nenhuma das duas partes é necessária para solicitações de PATCH. Ambos são necessários para POST ou criam operações.
O Código-fonte do Início Rápido da Ocupação contém exemplos de C# completos que demonstram como fazer solicitações com várias partes para as APIs de Gerenciamento dos Gêmeos Digitais do Azure.
Metadados de blob
Além de Content-Type e Content-Disposition, as solicitações multipartes de blob dos Gêmeos Digitais do Azure devem especificar o corpo JSON correto. Qual corpo JSON a ser enviado depende do tipo de operação de solicitação HTTP que está sendo executada.
Os quatro esquemas JSON principais são:
Metadados de blobs JSON são compatíveis com o seguinte modelo:
{
"parentId": "00000000-0000-0000-0000-000000000000",
"name": "My First Blob",
"type": "Map",
"subtype": "GenericMap",
"description": "A well chosen description",
"sharing": "None"
}
| Atributo | Tipo | Descrição |
|---|---|---|
| parentId | String | A entidade pai a ser associada ao blob (espaços, dispositivos ou usuários) |
| name | String | Um nome amigável para humanos para o blob |
| tipo | String | O tipo de blob – não é possível usar type e typeId |
| typeId | Inteiro | A ID do tipo de blob – não é possível usar type e typeId |
| subtype | String | O subtipo do blob – não é possível usar subtype e subtypeId |
| subtypeId | Inteiro | A ID do subtipo do blob – não é possível usar subtype e subtypeId |
| descrição | String | Descrição personalizada do blob |
| sharing | String | Se o blob pode ser compartilhado – enum [None, Tree, Global] |
Os metadados de blob são sempre fornecidos como a primeira parte com Content-Type application/json ou como um .json arquivo. Dados de arquivo são fornecidos na segunda parte e podem ser de qualquer tipo MIME com suporte.
A documentação do Swagger descreve esses esquemas de modelo em detalhes.
Dica
Uma versão prévia do Swagger é fornecida para demonstrar o conjunto de recursos da API. Ele está hospedado no docs.westcentralus.azuresmartspaces.net/management/swagger.
Você pode acessar sua própria documentação de Swagger da API de gerenciamento gerada em:
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| Nome | Substituir por |
|---|---|
| NOME_DA_SUA_INSTÂNCIA | O nome da sua instância de Gêmeos Digitais do Azure |
| SUA_LOCALIZAÇÃO | Em qual região do servidor de sua instância está hospedada |
Aprenda a usar a documentação de referência lendo Como usar o Swagger.
Dados de resposta de blobs
Blobs retornados individualmente estão em conformidade com o seguinte esquema JSON:
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "string",
"parentId": "00000000-0000-0000-0000-000000000000",
"type": "string",
"subtype": "string",
"typeId": 0,
"subtypeId": 0,
"sharing": "None",
"description": "string",
"contentInfos": [
{
"type": "string",
"sizeBytes": 0,
"mD5": "string",
"version": "string",
"lastModifiedUtc": "2019-01-12T00:58:08.689Z",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
],
"fullName": "string",
"spacePaths": [
"string"
]
}
| Atributo | Tipo | Descrição |
|---|---|---|
| id | String | O identificador exclusivo do blob |
| name | String | Um nome amigável para humanos para o blob |
| parentId | String | A entidade pai a ser associada ao blob (espaços, dispositivos ou usuários) |
| tipo | String | O tipo de blob – não é possível usar type e typeId |
| typeId | Inteiro | A ID do tipo de blob – não é possível usar type e typeId |
| subtype | String | O subtipo do blob – não é possível usar subtype e subtypeId |
| subtypeId | Inteiro | A ID do subtipo do blob – não é possível usar subtype e subtypeId |
| sharing | String | Se o blob pode ser compartilhado – enum [None, Tree, Global] |
| descrição | String | Descrição personalizada do blob |
| contentInfos | Array | Especifica as informações de metadados não estruturados, incluindo a versão |
| fullName | String | O nome completo do blob |
| spacePaths | String | O caminho de espaço |
Os metadados de blob são sempre fornecidos como a primeira parte com Content-Type application/json ou como um .json arquivo. Dados de arquivo são fornecidos na segunda parte e podem ser de qualquer tipo MIME com suporte.
Exemplos de solicitação com várias partes do blob
Nos exemplos a seguir, YOUR_MANAGEMENT_API_URL refere-se ao URI de APIs de Gêmeos Digitais:
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
| Nome | Substituir por |
|---|---|
| NOME_DA_SUA_INSTÂNCIA | O nome da sua instância de Gêmeos Digitais do Azure |
| SUA_LOCALIZAÇÃO | A região em que sua instância está hospedada |
Para carregar um arquivo de texto como um blob e associá-lo a um espaço, faça uma solicitação HTTP POST autenticada para:
YOUR_MANAGEMENT_API_URL/spaces/blobs
Com o seguinte corpo:
--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"
{
"ParentId": "54213cf5-285f-e611-80c3-000d3a320e1e",
"Name": "My First Blob",
"Type": "Map",
"SubType": "GenericMap",
"Description": "A well chosen description",
"Sharing": "None"
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="myblob.txt"
Content-Type: text/plain
This is my blob content. In this case, some text, but I could also be uploading a picture, an JSON file, a firmware zip, etc.
--USER_DEFINED_BOUNDARY--
| Valor | Substituir por |
|---|---|
| USER_DEFINED_BOUNDARY | Um nome de limite de conteúdo com diversas partes |
O código a seguir é uma implementação .NET do mesmo upload do Blob que usa a classe MultipartFormDataContent:
//Supply your metadata in a suitable format
var multipartContent = new MultipartFormDataContent("USER_DEFINED_BOUNDARY");
var metadataContent = new StringContent(JsonConvert.SerializeObject(metaData), Encoding.UTF8, "application/json");
metadataContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json; charset=utf-8");
multipartContent.Add(metadataContent, "metadata");
//MY_BLOB.txt is the String representation of your text file
var fileContents = new StringContent("MY_BLOB.txt");
fileContents.Headers.ContentType = MediaTypeHeaderValue.Parse("text/plain");
multipartContent.Add(fileContents, "contents");
var response = await httpClient.PostAsync("spaces/blobs", multipartContent);
Por fim, usuários de cURL podem fazer solicitações de formulário de várias partes da mesma maneira:
curl -X POST "YOUR_MANAGEMENT_API_URL/spaces/blobs" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F "meta={\"ParentId\":\"YOUR_SPACE_ID\",\"Name\":\"My CURL Blob\",\"Type\":\"Map\",\"SubType\":\"GenericMap\",\"Description\":\"A well chosen description\",\"Sharing\":\"None\"};type=application/json" \
-F "text=PATH_TO_FILE;type=text/plain"
| Valor | Substituir por |
|---|---|
| YOUR_TOKEN | Seu token OAuth 2.0 válido |
| YOUR_SPACE_ID | A ID do espaço a ser associado ao blob |
| PATH_TO_FILE | O caminho para seu arquivo de texto |
Um POST bem-sucedido retorna a ID do novo blob.
Pontos de extremidade de API
As seções a seguir descrevem os pontos de extremidade de API relacionados ao blob principal e suas funcionalidades.
Dispositivos
Você pode anexar blobs aos dispositivos. A imagem a seguir mostra a documentação de referência do Swagger para suas APIs de Gerenciamento. Ela especifica os pontos de extremidade da API relacionados ao dispositivo para consumo de blob e qualquer parâmetro de caminho necessário para passar para eles.
Por exemplo, para atualizar ou criar um blob e anexar o blob a um dispositivo, faça uma solicitação HTTP PATCH autenticada para:
YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID
| Parâmetro | Substituir por |
|---|---|
| YOUR_BLOB_ID | A ID do blob desejado |
Solicitações bem-sucedidas retornam um objeto JSON como descrito anteriormente.
Espaços
Você também pode anexar blobs aos espaços. A imagem abaixo lista todos os pontos de extremidade da API de espaços responsáveis pela manipulação dos blobs. Lista também os parâmetros de caminho a serem passados para esses pontos de extremidade.
Por exemplo, para retornar um blob anexado a um espaço, faça uma solicitação HTTP GET autenticada para:
YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID
| Parâmetro | Substituir por |
|---|---|
| YOUR_BLOB_ID | A ID do blob desejado |
Solicitações bem-sucedidas retornam um objeto JSON como descrito anteriormente.
Uma solicitação PATCH para o mesmo ponto de extremidade atualiza descrições de metadados e cria versões do blob. A solicitação HTTP é feita usando o método PATCH juntamente com quaisquer dados de formulário meta e multipartes necessários.
Usuários
Você pode anexar os blobs aos modelos do usuário (por exemplo, para associar uma imagem de perfil). A imagem abaixo exibe os pontos de extremidade relevantes da API de usuários e quaisquer parâmetros de caminho obrigatório, como id:
Por exemplo, para buscar um blob anexado a um usuário, faça uma solicitação HTTP GET autenticada com todos os dados de formulário necessários para:
YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID
| Parâmetro | Substituir por |
|---|---|
| YOUR_BLOB_ID | A ID do blob desejado |
Solicitações bem-sucedidas retornam um objeto JSON como descrito anteriormente.
Erros comuns
Um erro comum envolve não fornecer as informações corretas do cabeçalho:
{ "error": { "code": "400.600.000.000", "message": "Invalid media type in first section." } }Para resolver esse erro, verifique se a solicitação geral tem um cabeçalho Content-Type adequado:
multipart/mixedmultipart/form-data
Além disso, verifique se cada parte de várias partes tem um Content-Type correspondente apropriado.
Um segundo erro comum surge quando vários blobs são atribuídos ao mesmo recurso em seu gráfico de inteligência espacial:
{ "error": { "code": "400.600.000.000", "message": "SpaceBlobMetadata already exists." } }Observação
O atributo message varia de acordo com o recurso.
Apenas um blob (de cada tipo) pode ser anexado a cada recurso em seu gráfico espacial.
Para resolver esse erro, atualize o blob existente usando a operação PATCH HTTP DA API apropriada. Isso substituirá os dados de blob existentes pelos dados desejados.
Próximas etapas
Para obter mais informações sobre a documentação de referência do Swagger para Gêmeos Digitais do Azure, leia Como usar o Swagger dos Gêmeos Digitais do Azure.
Para carregar blobs por meio do Postman, leia Como configurar o Postman.