Usar contextos de objeto

Linha de comando

Para anexar contextos ao fazer upload de objetos com o comando gcloud alpha storage cp, use a flag --custom-contexts:

gcloud alpha storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME --custom-contexts=KEY=VALUE,...

Em que:

• OBJECT_LOCATION é o caminho local do objeto. Por exemplo, Desktop/dog.png.
• DESTINATION_BUCKET_NAME é o nome do bucket de upload do objeto. Por exemplo, my-bucket.
• KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor separados por vírgulas.
• VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

Outra opção é criar um arquivo JSON com os contextos que você quer anexar aos objetos e usar a flag --custom-contexts-file:

  {
    "KEY": {
      "value": "VALUE"
    },
    ...
  }

Em que:

• KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor.
• VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

Para anexar contextos ao fazer upload de diretórios com o comando gcloud alpha storage rsync, use a sinalização --custom-contexts ou --custom-contexts-file:

gcloud alpha storage rsync DIRECTORY_LOCATION gs://DESTINATION_BUCKET_NAME --recursive --custom-contexts=KEY=VALUE,...

Em que:

• DIRECTORY_LOCATION é o caminho local para o diretório. Por exemplo, ~/my_directory.
• DESTINATION_BUCKET_NAME é o nome do bucket de upload do diretório. Por exemplo, my-bucket.
• KEY é a chave de contexto a ser anexada aos objetos. Por exemplo, Department. É possível especificar vários pares de chave-valor separados por vírgulas.
• VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

API JSON

Para anexar contextos a objetos ao fazer upload de novos objetos, use qualquer um dos seguintes métodos:

• Uploads de várias partes

• Uploads recuperáveis

Como parte dos metadados do objeto no formato JSON, inclua o campo contexts:

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

Em que:

• KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor no objeto custom.
• VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

Linha de comando

Use o comando gcloud alpha storage objects update:

gcloud alpha storage objects update gs://BUCKET_NAME/OBJECT_NAME CUSTOM_CONTEXTS_FLAG

Em que:

• BUCKET_NAME é o nome do bucket que contém o objeto para o qual você quer editar o contexto. Por exemplo, my-bucket.
• OBJECT_NAME é o nome do objeto. Por exemplo, pets/dog.png.

• CUSTOM_CONTEXTS_FLAG é qualquer uma das seguintes flags:

  • Para substituir todos os contextos atuais, use --custom-contexts=KEY=VALUE,... ou --custom-contexts-file=CUSTOM_CONTEXTS_FILE

    Em que:

    • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor separados por vírgulas.
    • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.
    • CUSTOM_CONTEXTS_FILE é o caminho para o arquivo JSON ou YAML que contém os contextos que você quer anexar ao objeto.

  • Para excluir todos os contextos atuais, use --clear-custom-contexts.

  • Para adicionar, modificar ou excluir contextos individuais, use uma combinação de --update-custom-contexts=KEY=VALUE,... e --remove-custom-contexts=KEY,...

    Em que:

    • KEY é a chave de contexto que você quer anexar ou excluir de um objeto. Por exemplo, Department.
    • VALUE é o valor a ser associado à chave de contexto que você quer anexar a um objeto. Por exemplo, Human resources.

Se funcionar, a resposta será parecida com esta:

Patching gs://my-bucket/pets/dog.png#1560574162144861...
  Completed 1

Bibliotecas de cliente

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.collect.Maps;
import java.util.Map;

public class SetObjectContexts {
  public static void setObjectContexts(
      String projectId, String bucketName, String objectName, String key, String value)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The context key-value you want to add
    // String key = "your-context-key";
    // String value = "your-context-value";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      BlobId blobId = BlobId.of(bucketName, objectName);
      Blob blob = storage.get(blobId);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }

      // Recommended: Set a generation-match precondition to avoid potential race
      // conditions and data corruptions. The request to update returns a 412 error if
      // the object's generation number does not match your precondition.
      Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();

      // This section demonstrates how to upsert, delete all, and delete a specific context.

      // To upsert a context (if the key already exists, its value is replaced;
      // otherwise, a new key-value pair is added):
      ObjectCustomContextPayload payload =
          ObjectCustomContextPayload.newBuilder().setValue(value).build();
      Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
      custom.put(key, payload);
      ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();

      /*
       * To delete all existing contexts:
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(null).build();
       */

      /*
       * To delete a specific key from the context:
       * Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
       * custom.put(key, null);
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();
       */
      BlobInfo pendingUpdate = blob.toBuilder().setContexts(contexts).build();
      storage.update(pendingUpdate, precondition);

      System.out.println(
          "Updated custom contexts for object " + objectName + " in bucket " + bucketName);
    }
  }
}

API JSON

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

2. Crie um arquivo JSON que contenha as configurações do objeto, que precisam incluir os campos de configuração contexts do objeto.

   Para adicionar, modificar ou substituir contextos atuais, use o seguinte formato:

     {
       "contexts": {
         "custom": {
           "KEY": {
             "value": "VALUE"
           },
           ...
         }
       }
     }

   Em que:

   • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor no objeto custom.
   • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

   Para excluir todos os contextos atuais, use o seguinte formato:

     {
       "contexts": {
         "custom": null
       }
     }

   Para excluir uma chave específica do contexto, use o seguinte formato:

     {
       "contexts": {
         "custom": {
           "KEY": null,
           ...
         }
       }
     }

   Em que:

   KEY é a chave de contexto que você quer excluir de um objeto. Por exemplo, Department. É possível especificar várias chaves para excluir do objeto custom.

3. Use cURL para chamar a API JSON com uma solicitação de objeto PATCH:

   curl -X PATCH --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

   Em que:

   • JSON_FILE_NAME é o caminho para o arquivo que inclui as informações de contextos de objetos.
   • BUCKET_NAME é o nome do bucket que contém o objeto com o contexto que você quer editar. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL do objeto. Por exemplo, pets/dog.png é codificado em URL como pets%2Fdog.png.

Como alternativa, você pode substituir o contexto de um objeto por uma solicitação PUT Object. A solicitação de objeto PUT também substitui outros metadados de objeto. Portanto, não recomendamos usar a solicitação de objeto PUT.

Linha de comando

Use o comando gcloud alpha storage objects describe:

gcloud alpha storage objects describe gs://BUCKET_NAME/OBJECT_NAME

Em que:

• BUCKET_NAME é o nome do bucket que contém o objeto com o contexto que você quer ver. Por exemplo, my-bucket.
• OBJECT_NAME é o nome do objeto com o contexto que você quer ver. Por exemplo, pets/dog.png

Se a operação for bem-sucedida, a resposta será semelhante a esta:

bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt

Bibliotecas de cliente

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetObjectContexts {
  public static void getObjectContexts(String projectId, String bucketName, String objectName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {

      Blob blob = storage.get(bucketName, objectName);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }
      ObjectContexts objectContexts = blob.getContexts();

      if (objectContexts != null) {
        Map<String, ObjectCustomContextPayload> customContexts = objectContexts.getCustom();
        if (customContexts == null) {
          System.out.println("No custom contexts found for object: " + objectName);
          return;
        }
        // Print blob's object contexts
        System.out.println("\nCustom Contexts:");
        for (Map.Entry<String, ObjectCustomContextPayload> custom : customContexts.entrySet()) {
          System.out.println(custom.getKey() + "=" + custom.getValue());
        }
      }
    }
  }
}

API JSON

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

2. Use cURL para chamar a API JSON com uma solicitação de objeto GET:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

   Em que:

   • BUCKET_NAME é o nome do bucket que contém o objeto com o contexto que você quer ver. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL do objeto com o contexto que você quer ver. Por exemplo, pets/dog.png, codificado em URL como pets%2Fdog.png.

   Se a operação for bem-sucedida, a resposta será semelhante a esta:

     {
       "kind": "storage#object",
       "name": "employees.txt",
       "bucket": "my-bucket",
       "contexts": {
         "custom": {
           "Department": {
             "value": "HR",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           },
           "DataClassification": {
             "value": "Confidential",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           }
         }
       }
     }
     

Linha de comando

Os comandos gcloud alpha storage cp, gcloud alpha storage rsync e gcloud alpha storage mv preservam os contextos do objeto de origem por padrão. Para modificar contextos durante essas operações, use qualquer uma das seguintes flags:

• As flags --custom-contexts ou --custom-contexts-file para definir novos contextos para o objeto de destino.
• A flag --clear-custom-contexts para impedir que contextos do objeto de origem sejam anexados ao objeto de destino.
• Uma combinação das flags --update-custom-contexts e --remove-custom-contexts para modificar contextos individuais do objeto de origem antes de anexá-los ao objeto de destino.

O comando gcloud alpha storage objects compose mescla contextos dos objetos de origem e os anexa aos objetos de destino por padrão. O Cloud Storage resolve conflitos priorizando contextos de objetos de origem processados posteriormente. Para mais informações sobre o comportamento do contexto de objeto durante uma operação de composição, consulte Contextos de objetos compostos. Também é possível especificar novos contextos para o objeto de destino usando as flags --custom-contexts ou --custom-contexts-file.

API JSON

• Para modificar contextos durante uma operação de objeto cópia ou regravação, inclua a propriedade contexts.custom no corpo da solicitação. Se você não incluir essa propriedade, os contextos do objeto de origem serão preservados por padrão.

• Quando você compõe objetos, os contextos dos objetos de origem são mesclados ao objeto de destino por padrão. O Cloud Storage resolve conflitos priorizando contextos de objetos de origem processados posteriormente. Para mais informações sobre o comportamento do contexto de objeto durante uma operação de composição, consulte Contextos de objetos compostos. Você também pode especificar novos contextos para o objeto de destino na propriedade destination.contexts.custom.