Gerenciar versões

Esta página se aplica à Apigee e à Apigee híbrida.

Este tópico explica como criar e gerenciar versões da API. Para saber mais sobre as versões, consulte a Visão geral das versões.

Adicionar uma versão a uma API

É possível adicionar uma versão da API a uma API no console ou com a API REST.

Console

Para adicionar uma nova versão:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API que você quer controlar. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Clique em uma API para conferir os detalhes.
Na guia Versões, clique em Adicionar versão.
Especifique os detalhes no formulário Adicionar uma nova versão. Forneça um nome de exibição. Os outros atributos são opcionais. Para mais informações sobre atributos, consulte Gerenciar atributos.
- Nome : (obrigatório) é necessário informar um nome de exibição.
- Descrição: adicione uma descrição da versão.
- Ciclo de vida: selecione o estágio do ciclo de vida da API.
- Compliance: selecione um atributo de compliance.
- Credenciamento: selecione um atributo de certificação.
- Documentation: insira o URL da documentação da API.
- Adicionar um arquivo de especificação: importe um arquivo de especificações para associar à versão. Consulte Adicionar uma especificação de API a uma versão.
- Vincular a uma implantação: selecione uma ou mais implantações para associar à API.
- Atributos definidos pelo usuário: esses atributos são definidos com base nas necessidades da sua organização ou equipe. Consulte Atributos do usuário.
Clique em Criar.

REST

Para adicionar uma nova versão usando a API Create an API version:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions?version_id=VERSION_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X POST -H "Content-Type: application/json" \
  '{
    "display-name": "DISPLAY_NAME",
    "description": "DESCRIPTION"               # description is an optional attribute
    }'

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API ao qual a versão será adicionada.
VERSION_ID: (opcional) o identificador da versão da API. Caso não seja informado, um ID gerado pelo sistema será usado. O nome precisa ser uma string de 4 a 63 caracteres, em que os caracteres válidos são /[a-z][0-9]-/.
DISPLAY_NAME: (obrigatório) o nome de exibição da versão. Use o nome que preferir.
DESCRIPTION: (opcional) você pode adicionar diversos atributos opcionais para descrever a versão, incluindo uma descrição, um nome de proprietário, um link para a documentação e muito mais. Esses atributos opcionais são listados e descritos na Definição do recurso de versão.

Exemplo de resposta:

{
  "name": "projects/myproject/locations/myproject/apis/docs-api-1/versions/myversion1",
  "displayName": "My Version 1",
  "createTime": "2024-04-02T18:48:41.162360Z",
  "updateTime": "2024-04-02T18:48:41.162360Z"
}

Listar versões da API

Esta seção explica como listar as versões associadas a uma API registrada.

Console

Para visualizar todas as versões associadas a uma API registrada no console:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API que você quer inspecionar. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Selecionar uma API.
As versões são listadas na tabela Versões na página de detalhes da API.

REST

Para conferir todas as versões associadas a uma API registrada usando a API List API version:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -H "Content-Type: application/json"

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API.

Exemplo de resposta:

{
  "versions": [
    {
      "name": "projects/myproject/locations/us-central1/apis/streetcarts-test/versions/streetcarts-testv1",
      "displayName": "Streetcarts Test v1"
    }
  ]
}

Receber detalhes da versão da API

Esta seção explica como ver os detalhes de uma versão da API, incluindo atributos, operações, implantações e arquivos de especificação.

Console

Para ver os detalhes da versão no console:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API que você quer inspecionar. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Selecionar uma API.
Na tabela Versões, clique em uma versão para conferir a página de detalhes.

REST

Para consultar os detalhes de uma versão usando a API Get API version details:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API.
VERSION_ID: o ID exclusivo da versão.

Exemplo de resposta:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/specs/docs-spec-1"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Excluir uma versão da API

Nesta seção, explicamos como excluir uma versão de API associada a um recurso de API.

Console

Quando você exclui uma versão na interface, todas as especificações associadas à versão (se houver) são excluídas.

Para excluir uma versão:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API que inclui a versão que você quer excluir. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Selecionar uma API.
Na tabela Versões, encontre a versão que você quer excluir.
No menu Ações (à direita da linha que contém a versão), clique em Excluir.

REST

Por padrão, uma versão só pode ser excluída se todas as especificações forem excluídas. Se você quiser excluir todas as especificações de uma versão em uma única etapa, defina o parâmetro de consulta force como true na API REST Delete.

Para excluir uma versão usando a API Delete API version:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID'

Substitua:

API_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
API_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API.
VERSION_ID: o ID da versão a ser excluída.

Para excluir uma versão e todas as especificações, defina o parâmetro de consulta force como true. Exemplo:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID?force=true'

Editar uma versão

Console

Para editar uma versão:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Selecionar uma API.
Na tabela Versões, localize a versão que você quer editar.
Selecione Editar no menu Ações no lado direito da linha da versão. Também é possível acessar o recurso de edição clicando em Editar versão na página de detalhes da versão. Para acessar a página de detalhes, basta clicar em uma versão na tabela de versões.
Depois de fazer as edições, clique em Salvar para manter as mudanças. Para ver uma descrição dos atributos editáveis, consulte a descrição do recurso de versão na referência da API REST.

REST

Para editar uma versão com a API REST, siga estas etapas:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID?updateMask=LIST_OF_ATTRIBUTES"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json" \
    '{
      "display-name": DISPLAY_NAME,  # Use the request body to specify attribute changes
      "description": "DESCRIPTION"

    }'

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo da API que tem a versão que você quer editar.
VERSION_ID: o ID da versão a ser editada.
DESCRIPTION: é possível adicionar outros atributos editáveis no corpo da solicitação, como a descrição e outros. Os atributos editáveis estão listados na referência da API Apigee Hub. a API Patch version.
LIST_OF_ATTRIBUTES: uma lista separada por vírgulas de nomes de atributos totalmente qualificados. Por exemplo, ?updateMask="description".

Exemplo de resposta:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts-test/versions/streetcarts-testv1",
  "displayName": "Streetcarts Test v1",
  "description": "This is a revision of the test version.",
  "documentation": {},
  "createTime": "2024-04-18T19:57:11.870761Z",
  "updateTime": "2024-04-18T20:23:42.465324Z"
}