O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Configurar o enriquecimento de objetos

Para gerar metadados estruturados de imagens e documentos PDF nos seus buckets do Cloud Storage, crie um recurso de configuração de recursos (FeatureConfig). Você também precisa autorizar o agente de serviço de enriquecimento de objetos a acessar seus dados. Depois de configurar os enriquecimentos de objetos, o Cloud Storage avalia os objetos correspondentes com os modelos de machine learning escolhidos de forma assíncrona e anexa os resultados diretamente aos objetos como contextos de objeto.

Nesta página, explicamos como criar, listar, visualizar, atualizar e excluir configurações de recursos. Também explicamos como conceder as permissões necessárias do Identity and Access Management (IAM) ao agente de serviço.

O fluxo de trabalho completo envolve as seguintes etapas:

Crie um recurso de configuração de atributos (FeatureConfig) para definir seu escopo e selecionar modelos.
Autorize o agente de serviço a acessar seus buckets de armazenamento.
Ver e gerenciar metadados de enriquecimento nos seus objetos.
Analise seus enriquecimentos em massa usando SQL no BigQuery.
Atualize ou exclua as configurações de recursos à medida que sua carga de trabalho evolui.

Para detalhes conceituais e casos de uso compatíveis, consulte a visão geral dos enriquecimentos de objetos.

Antes de começar

Antes de configurar os enriquecimentos de objetos, siga estas etapas de configuração:

Ter os papéis necessários

Para receber as permissões necessárias para criar e gerenciar configurações de recursos, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar e gerenciar configurações de recursos. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar e gerenciar configurações de recursos:

storage.featureConfigs.create
storage.featureConfigs.list
storage.featureConfigs.get
storage.featureConfigs.update
storage.featureConfigs.delete

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

(Opcional) Preparar conjuntos de dados do Storage Insights para análise SQL

Se você planeja consultar e analisar metadados de enriquecimento em milhões de objetos usando SQL no BigQuery, primeiro configure conjuntos de dados do Storage Insights. Os conjuntos de dados do Storage Insights exportam automaticamente os contextos de objetos diretamente para tabelas consultáveis do BigQuery.

Se você quiser inspecionar apenas objetos individuais usando o console do Google Cloud , a Google Cloud CLI ou uma API, pule esta etapa.

Criar uma configuração de recurso

Uma configuração de recurso (FeatureConfig) especifica quais buckets de armazenamento o Cloud Storage monitora e quais modelos de machine learning avaliam seus objetos. Especifique os nomes exatos dos buckets na configuração. Os enriquecimentos de objetos não são compatíveis com expressões regulares ou caracteres curinga. Se você criar, recriar (excluir e criar novamente) ou realocar buckets depois de criar uma configuração, será necessário atualizar a configuração do recurso para incluí-los. Para mais informações, consulte Gerenciamento de configuração e escopo.

É possível criar uma configuração de recurso usando o console do Google Cloud , a Google Cloud CLI ou a API JSON.

Console

No console do Google Cloud , acesse a página Enriquecimentos de objetos do Cloud Storage.

Acessar o enriquecimento de objetos
Clique em Criar.
Na etapa Definir origem, especifique o nome da configuração e os intervalos de destino:
1. No campo Nome, insira um nome exclusivo para a configuração do recurso. O nome precisa ter de 1 a 63 caracteres e conter apenas letras minúsculas, números ou hifens. Ele precisa começar com uma letra minúscula e não pode terminar com um hífen. Não é possível mudar esse nome depois de criar a configuração.
2. Opcional: para ajudar a identificar a configuração, insira uma descrição (até 256 caracteres) no campo Descrição.
3. Para especificar os buckets que você quer enriquecer, insira um ou mais nomes de bucket separados por vírgulas ou espaços no campo Nomes de bucket. Como alternativa, clique em Procurar, selecione um bucket e clique em Selecionar.
4. Clique em Continuar.
Na etapa Selecionar modelos, marque as caixas de seleção de um ou mais modelos de machine learning que você quer ativar e clique em Continuar:
- Detecção de objetos em imagens (object-detector): identifica e localiza vários objetos em uma imagem.
- Detecção facial em imagens (face-detector): detecta rostos humanos e os atributos deles em imagens.
- Rotulagem de imagens (label-detector): atribui rótulos a imagens com base no conteúdo delas.
- Detecção de conteúdo explícito em imagens (content-safety): detecta conteúdo adulto, violento ou sensível.
- Classificação de PDF (pdf-classification): identifica a categoria do assunto do documento.
Para detalhes sobre cada modelo e o esquema de saída, consulte Modelos e esquemas compatíveis.
Na etapa Selecionar local de processamento, no menu Local de processamento, selecione um local multirregional (us, eu ou asia) e clique em Continuar.
Na etapa Conceder permissões necessárias, escolha como conceder os papéis do IAM necessários ao agente de serviço de enriquecimento de objetos:
- Conceder permissão para todo o projeto: concede automaticamente ao agente de serviço os papéis necessários (roles/storage.annotationGeneratorService e roles/storage.bucketViewer) para processar todos os buckets do Cloud Storage atuais e futuros no projeto. Para selecionar essa opção, é preciso ter a permissão resourcemanager.projects.setIamPolicy no projeto. Se você não tiver essa permissão, a opção não estará disponível.
- Fornecer permissão de concessão manualmente mais tarde: cria a configuração sem conceder permissões imediatamente. É preciso conceder permissões ao agente de serviço antes que o Cloud Storage possa processar objetos.
Clique em Criar.

A criação de uma configuração de recurso inicia uma operação de longa duração. Quando a operação for concluída, o console Google Cloud vai abrir a página de detalhes da configuração. Se você selecionou Conceder permissão para todo o projeto, o console do Google Cloud aplicará as vinculações de política do IAM depois de criar a configuração.

Linha de comando

Para criar uma configuração de recurso, use o comando gcloud alpha storage feature-configs create:

gcloud alpha storage feature-configs create FEATURE_CONFIG_ID \
    --description="DESCRIPTION" \
    --auto-annotate-models=MODELS \
    --auto-annotate-processing-location=PROCESSING_LOCATION \
    --include-bucket-id-regexes=BUCKET_NAME

Em que:

FEATURE_CONFIG_ID é um ID exclusivo para a configuração do recurso. Precisa ter de 1 a 63 caracteres, começar com uma letra minúscula e conter apenas letras minúsculas, números ou hifens. Não pode terminar com um hífen.
DESCRIPTION é uma descrição opcional para a configuração do recurso. Por exemplo, Scan invoices and receipts.
MODELS é uma lista separada por vírgulas dos modelos de aprendizado de máquina a serem ativados: face-detector, object-detector, label-detector, content-safety ou pdf-classification. Para detalhes sobre cada modelo e o esquema de saída, consulte Modelos e esquemas compatíveis.
PROCESSING_LOCATION é o local de tratamento multirregional em que o tratamento de dados ocorre. Os valores compatíveis são us, eu ou asia.
BUCKET_NAME é o nome exato de um bucket a ser incluído nesta configuração. É possível especificar uma lista separada por vírgulas de nomes exatos de buckets.

API JSON

Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.
Crie um arquivo JSON que contenha as configurações do recurso:
```
{
  "description": "DESCRIPTION",
  "autoAnnotateConfig": {
    "models": [
      { "name": "MODEL_NAME" }
    ],
    "processingLocation": "PROCESSING_LOCATION"
  },
  "filter": {
    "includedCloudStorageBuckets": {
      "bucketIdRegexes": [
        "BUCKET_NAME"
      ]
    }
  }
}
```
Em que:
- DESCRIPTION é uma descrição opcional para a configuração do recurso. Por exemplo, Scan invoices and receipts.
- MODEL_NAME é o nome de um modelo de machine learning para ativar: face-detector, object-detector, label-detector, content-safety ou pdf-classification. Para detalhes sobre cada modelo e o esquema de saída, consulte Modelos e esquemas compatíveis. Para ativar vários modelos, adicione outros objetos de modelo à matriz models.
- PROCESSING_LOCATION é o local de processamento multirregional onde ocorre o tratamento de dados. Os valores compatíveis são us, eu ou asia.
- BUCKET_NAME é o nome exato de um bucket a ser incluído na configuração. Por exemplo, my-bucket. Para incluir vários buckets, especifique outras strings de nome de bucket na matriz bucketIdRegexes.
Use cURL para enviar uma solicitação featureConfigs.create à API JSON:
```
curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs?featureConfigId=FEATURE_CONFIG_ID"
```
Em que:
- JSON_FILE_NAME é o caminho para o arquivo JSON que você criou na etapa anterior. Por exemplo, config.json.
- PROJECT_ID é o ID do projeto do Google Cloud . Por exemplo, my-project.
- FEATURE_CONFIG_ID é um ID exclusivo para a configuração do recurso. Por exemplo, my-feature-config. Precisa ter de 1 a 63 caracteres, começar com uma letra minúscula e conter apenas letras minúsculas, números ou hifens. Não pode terminar com um hífen.
Opcional: para verificar o status da operação de longa duração para criar a configuração do recurso, use cURL para enviar uma solicitação operations.get à API JSON:
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/operations/OPERATION_ID"
```
Em que:
- PROJECT_ID é o ID do projeto do Google Cloud . Por exemplo, my-project.
- OPERATION_ID é o ID da operação retornado na resposta de criação.
Opcional: para listar todas as operações ativas e históricas, use cURL para enviar uma solicitação operations.list à API JSON:
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/operations"
```
Em que PROJECT_ID é o ID do projeto do Google Cloud. Por exemplo, my-project.

Conceder permissões ao agente de serviço

Quando você cria uma configuração de recurso,o Google Cloud provisiona um agente de serviço dedicado para seu projeto: service-PROJECT_NUMBER@gcp-sa-autoannotate.iam.gserviceaccount.com.

Para permitir que esse agente de serviço verifique seus buckets, leia objetos não estruturados e anexe metadados de enriquecimento, conceda a ele os papéis do IAM necessários.

Console

Se você selecionou Fornecer permissão de concessão manualmente mais tarde ao criar uma configuração de recurso ou se precisar reaplicar permissões em todo o projeto, é possível conceder permissões na página de detalhes da configuração:

No console do Google Cloud , acesse a página Enriquecimentos de objetos do Cloud Storage.

Acessar o enriquecimento de objetos
Na coluna Nome da configuração, clique no nome da configuração do recurso.
Na barra de ações, clique em Conceder permissões.
No painel Conceder permissões, clique em Conceder permissões em todo o projeto.

Essa ação concede ao agente de serviço os papéis de Serviço de gerador de anotações do Storage (roles/storage.annotationGeneratorService) e Leitor de buckets do Storage (roles/storage.bucketViewer) no projeto. Para conceder permissões em todo o projeto no console Google Cloud , é preciso ter a permissão resourcemanager.projects.setIamPolicy no projeto.

Para conceder o papel roles/storage.annotationGeneratorService em buckets individuais em vez de todo o projeto, use a Google Cloud CLI.

Linha de comando

Conceda o papel Serviço gerador de anotações de armazenamento (roles/storage.annotationGeneratorService) ao agente de serviço em cada bucket monitorado ou no nível do projeto:
- Para conceder o papel em um bucket específico, use o comando gcloud storage buckets add-iam-policy-binding:
```
gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.iam.gserviceaccount.com \
    --role=roles/storage.annotationGeneratorService
```
  Em que:
  - BUCKET_NAME é o nome do bucket em que você quer conceder permissões.
  - PROJECT_NUMBER é o número do projeto do Google Cloud.
- Para conceder o papel em todos os buckets do projeto, use o comando gcloud projects add-iam-policy-binding:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.iam.gserviceaccount.com \
    --role=roles/storage.annotationGeneratorService
```
  Em que:
  - PROJECT_ID é o ID do projeto do Google Cloud.
  - PROJECT_NUMBER é o número do projeto do Google Cloud.
Para conceder o papel Leitor de buckets do Storage (roles/storage.bucketViewer) no nível do projeto para que o agente de serviço possa inspecionar as configurações do bucket, use o comando gcloud projects add-iam-policy-binding:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.iam.gserviceaccount.com \
    --role=roles/storage.bucketViewer
```
Em que:
- PROJECT_ID é o ID do projeto do Google Cloud .
- PROJECT_NUMBER é o número do projeto do Google Cloud.

Depois de conceder papéis, as permissões do IAM podem levar alguns minutos para serem propagadas antes do início do processamento assíncrono.

Listar todas as configurações de recursos

Para listar todas as configurações de recursos no seu projeto, siga estas etapas:

Console

No console do Google Cloud , acesse a página Enriquecimentos de objetos do Cloud Storage.

Acessar o enriquecimento de objetos

A guia Configuração lista todas as configurações de recursos no seu projeto, incluindo os modelos ativados, o local de processamento, o escopo, os filtros de bucket, a data de criação e a data da última atualização.
Opcional: para filtrar a lista, insira o nome ou valor de uma propriedade no campo Filtro.

Linha de comando

Use o comando gcloud alpha storage feature-configs list:

gcloud alpha storage feature-configs list

API JSON

Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

Use cURL para enviar uma solicitação featureConfigs.list para a API JSON:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs"

Em que PROJECT_ID é o ID do projeto do Google Cloud . Por exemplo, my-project.

Ver detalhes da configuração do recurso

Para inspecionar os modelos, os buckets de destino e o local de processamento de uma configuração de recurso específica, siga estas etapas:

Console

No console do Google Cloud , acesse a página Enriquecimentos de objetos do Cloud Storage.

Acessar o enriquecimento de objetos
Na coluna Nome da configuração, clique no nome da configuração do recurso que você quer inspecionar.

A página de detalhes da configuração mostra o nome, a descrição, o escopo, os buckets incluídos, o local de processamento, os modelos ativados, a data de criação e a data da última atualização.

Linha de comando

Use o comando gcloud alpha storage feature-configs describe:

gcloud alpha storage feature-configs describe FEATURE_CONFIG_ID

Substitua FEATURE_CONFIG_ID pelo ID da configuração do recurso.

API JSON

Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.
Use cURL para enviar uma solicitação featureConfigs.get à API JSON:
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID"
```
Em que:
- PROJECT_ID é o ID do projeto doGoogle Cloud . Por exemplo, my-project.
- FEATURE_CONFIG_ID é o ID da configuração do recurso. Por exemplo, my-feature-config.

Atualizar uma configuração de recurso

É possível atualizar uma configuração de recurso existente para adicionar ou remover modelos de aprendizado de máquina, mudar os buckets de destino, modificar o local de processamento ou atualizar a descrição.

Console

No console do Google Cloud , acesse a página Enriquecimentos de objetos do Cloud Storage.

Acessar o enriquecimento de objetos
Na coluna Nome da configuração, clique no nome da configuração do recurso que você quer atualizar.
Na página de detalhes da configuração, atualize as configurações que você quer mudar:
- Para atualizar a descrição, clique em Editar descrição da configuração ao lado de Descrição da configuração. No painel Editar descrição, atualize o texto no campo Descrição e clique em Salvar.
- Para atualizar o escopo do bucket, clique em Editar escopo da configuração ao lado de Escopo da configuração. Na etapa Definir escopo, adicione ou remova buckets de destino no campo Nomes de buckets e clique em Continuar. Na etapa Conceder permissões necessárias, selecione uma opção de permissão para o agente de serviço e clique em Salvar.
- Para atualizar o local de processamento, clique em Editar local de processamento da configuração ao lado de Local de processamento. No painel Editar local de processamento, selecione um local multirregional (us, eu ou asia) no menu Local de processamento e clique em Salvar.
- Para atualizar os modelos ativados, clique em Editar modelos com configuração ativada ao lado de Modelos ativados. No painel Editar modelos, marque ou desmarque as caixas de seleção dos modelos que você quer atualizar e clique em Salvar.

Linha de comando

Use o comando gcloud alpha storage feature-configs update para atualizar a descrição, os modelos, o local de processamento ou os filtros de bucket:

gcloud alpha storage feature-configs update FEATURE_CONFIG_ID \
    --description="DESCRIPTION" \
    --auto-annotate-models=MODELS \
    --auto-annotate-processing-location=PROCESSING_LOCATION \
    --include-bucket-id-regexes=BUCKET_NAME

Substitua:

FEATURE_CONFIG_ID: o ID da configuração de recurso que você está atualizando.
DESCRIPTION: uma descrição opcional para a configuração do recurso. Por exemplo, Scan invoices and receipts.
MODELS: uma lista separada por vírgulas de modelos de machine learning a serem ativados: face-detector, object-detector, label-detector, content-safety ou pdf-classification.
PROCESSING_LOCATION: o local de processamento multirregional em que o tratamento de dados ocorre. Os valores válidos são us, eu ou asia.
BUCKET_NAME: uma lista separada por vírgulas de nomes de intervalos exatos a serem verificados. Os enriquecimentos de objetos não são compatíveis com caracteres curinga ou expressões regulares. Se você criar, recriar ou realocar buckets, atualize essa lista para incluí-los.

API JSON

Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.
Crie um arquivo JSON que contenha as configurações que você quer atualizar. Por exemplo, para atualizar a descrição, os modelos ativados e os intervalos de destino:
```
{
  "description": "DESCRIPTION",
  "autoAnnotateConfig": {
    "models": [
      { "name": "MODEL_NAME" }
    ],
    "processingLocation": "PROCESSING_LOCATION"
  },
  "filter": {
    "includedCloudStorageBuckets": {
      "bucketIdRegexes": [
        "BUCKET_NAME"
      ]
    }
  }
}
```
Em que:
- DESCRIPTION é uma descrição opcional para a configuração do recurso. Por exemplo, Scan invoices and receipts.
- MODEL_NAME é o modelo de machine learning a ser incluído: face-detector, object-detector, label-detector, content-safety ou pdf-classification. Para detalhes sobre cada modelo e o esquema de saída, consulte Modelos e esquemas compatíveis. Para ativar vários modelos, adicione outros objetos de modelo à matriz models.
- PROCESSING_LOCATION é o local de processamento multirregional onde ocorre o tratamento de dados. Os valores válidos são us, eu ou asia.
- BUCKET_NAME é o nome exato de um bucket a ser incluído na verificação. Por exemplo, my-bucket. Os enriquecimentos de objetos não são compatíveis com expressões regulares ou caracteres curinga. Se você criar, recriar ou realocar buckets, será necessário atualizar essa lista para incluí-los. Para incluir vários buckets, especifique outras strings de nome de bucket na matriz bucketIdRegexes.
Use cURL para enviar uma solicitação featureConfigs.patch para a API JSON:
```
curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID?updateMask=UPDATE_MASK"
```
Em que:
- JSON_FILE_NAME é o caminho local para o arquivo de solicitação JSON criado na Etapa 2. Por exemplo, update.json.
- PROJECT_ID é o ID do projeto doGoogle Cloud . Por exemplo, my-project.
- FEATURE_CONFIG_ID é o ID da configuração do recurso a ser atualizada. Por exemplo, my-feature-config.
- UPDATE_MASK é uma lista separada por vírgulas de campos que você quer atualizar, como description,filter ou autoAnnotateConfig.models. Para regras de sintaxe, consulte FieldMask.

Excluir uma configuração de recurso

A exclusão de uma configuração de recurso impede que o Cloud Storage gere novas melhorias para buckets correspondentes. A exclusão de uma configuração não exclui as melhorias já anexadas aos objetos armazenados.

Para excluir uma configuração de recurso, siga estas etapas:

Console

No console do Google Cloud , acesse a página Enriquecimentos de objetos do Cloud Storage.

Acessar o enriquecimento de objetos
Na coluna Nome da configuração, clique no nome da configuração do recurso que você quer excluir e em Excluir.
Na caixa de diálogo, clique em Confirmar.

Linha de comando

Use o comando gcloud alpha storage feature-configs delete:

gcloud alpha storage feature-configs delete FEATURE_CONFIG_ID

Substitua FEATURE_CONFIG_ID pelo ID da configuração do recurso.

API JSON

Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.
Use cURL para enviar uma solicitação featureConfigs.delete para a API JSON:
```
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID"
```
Em que:
- PROJECT_ID é o ID do projeto doGoogle Cloud . Por exemplo, my-project.
- FEATURE_CONFIG_ID é o ID da configuração do recurso a ser excluída. Por exemplo, my-feature-config.

Configurar o enriquecimento de objetos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Ter os papéis necessários

Permissões necessárias

(Opcional) Preparar conjuntos de dados do Storage Insights para análise SQL

Criar uma configuração de recurso

Console

Linha de comando

API JSON

Conceder permissões ao agente de serviço

Console

Linha de comando

Listar todas as configurações de recursos

Console

Linha de comando

API JSON

Ver detalhes da configuração do recurso

Console

Linha de comando

API JSON

Atualizar uma configuração de recurso

Console

Linha de comando

API JSON

Excluir uma configuração de recurso

Console

Linha de comando

API JSON

A seguir

Configurar o enriquecimento de objetos