Introdução ao Centro de API
Neste exercício, você vai:
Crie um serviço do Centro de API.
Definir propriedades de metadados.
Adicione APIs ao Centro de API.
Adicionar implantações e ambientes.
Pré-requisitos
Para começar a gerenciar suas APIs por meio do Centro de API, você precisa de:
- Uma assinatura do Azure.
- O provedor de recursos Microsoft.ApiCenter registrado em sua assinatura.
- No mínimo, uma atribuição da função Colaborador ou permissões equivalentes na assinatura do Azure.
Observação
Caso ainda não tenha feito isso, você precisará registrar o provedor de recursos Microsoft.ApiCenter em sua assinatura.
- Entre no portal do Azure.
- Insira Assinaturas na barra de pesquisa.
- Selecione a assinatura em que você deseja criar o Centro de API.
- No menu à esquerda, em selecione Recursos de provedores de recursos.No menu à esquerda, em Recursos, selecione Provedores de recursos.
- Pesquise por Microsoft.ApiCenter na lista de provedores de recursos. Se não estiver registrado, selecione Registrar.
Etapa 1: Criar um serviço do Centro de API
Entre no portal do Azure.
Insira os Centros de API na barra de pesquisa.
Selecione + Criar.
Na guia Básico, selecione ou insira as seguintes configurações:
a. Selecione sua assinatura do Azure.
b. Selecione um grupo de recursos ou selecione Novo para criar um.
c. Insira um Nome para seu Centro de API. Ele deve ser exclusivo na região em que você está criando seu centro de API.
d. Em Região, selecione uma das regiões disponíveis para o Centro de API.
e. Para o plano de preços, selecione Avaliação gratuita (US$ 0 por 90 dias).
f. Selecione Examinar + criar.
.h Depois de concluir a validação, selecione Criar.
Após a implantação, seu API center estará pronto para ser usado!
Para executar comandos de referência da CLI localmente, instale a CLI do Azure e faça logon usando o comando a seguir.
az login
Observação
Caso ainda não tenha feito isso, você precisará registrar o provedor de recursos Microsoft.ApiCenter em sua assinatura.
Execute o seguinte comando para registrar o provedor de recursos:
az provider register –namespace Microsoft.ApiCenter
Etapa 1: Criar um serviço do Centro de API
Crie um grupo de recursos do Azure executando o seguinte comando e passando:
- Exemplo de nome do grupo de recursos --name. Contoso
- Exemplo de local --location. Eastus
az group create –-name contoso –-location eastus
Observação
comandos az apic exigem a extensão apic-extension CLI do Azure. Se você não tiver usado comamdoz apic , a extensão será instalada dinamicamente quando você executar seu primeiro comando az apic ou você poderá instalar a extensão manualmente. Saiba mais sobre as extensões da CLI do Azure.
Crie um Centro de API executando o seguinte comando e passando:
- Exemplo de nome de centro de serviço de API -n. contoso-apis
- Exemplo do grupo de recursos -g. Contoso
- Exemplo de local --l. Eastus
az apic create -n contoso-apis -g contoso -l eastus
Observação
Por padrão, o Centro de API será criado no Tipo de preço gratuito.
Observação
No momento, não há suporte para a criação de um serviço do Centro de API no VS Code. Crie um usando a CLI do Azure ou o portal do Azure.
Etapa 2: Definir propriedades de metadados
O Centro de API usa propriedades de metadados para organizar as APIs em seu inventário e habilitar operações como filtragem, pesquisa etc.
Observação
Não inclua informações confidenciais nem pessoais nos nomes/títulos das propriedades de metadados.
A Contoso, como muitas outras organizações, gostaria que todas as APIs passassem por um aprovador antes de ficarem disponíveis para uso e de garantir que uma revisão de conformidade seja realizada para todas as APIs. A organização também tem APIs voltadas para o público e aquelas criadas exclusivamente apenas para uso interno. Para impor isso em escala em todas as APIs, adicionamos três propriedades de metadados personalizadas:
- Aprovador de API do tipo cadeia de caracteres
- Revisão de conformidade do tipo Opções predefinidas
- Voltado para o público do tipo booliano
No menu à esquerda, selecione Ativos > Metadados > + Novos metadados.
Na guia Details, insira as informações sobre a propriedade.
a. Em Título, insira Aprovador de API
b. Em Descrição, insira Aprovador de API Padrão
c. Selecione o tipo Cadeia de Caracteres e selecione Avançar
Na guia Atribuições, selecione Obrigatório para APIs. Selecione Opcional para Implantações e Ambientes. Selecione Avançar
Escolha Criar
Repita as mesmas etapas para a propriedade Voltado para o público, conforme mostrado na imagem abaixo. Para o tipo, selecione Booliano
Na guia Atribuições, selecione Obrigatório para APIs. Selecione Não aplicável para Implantações e Ambientes. Selecione Avançar
Escolha Criar
Repita as mesmas etapas para a propriedade Revisão de conformidade, conforme mostrado na imagem abaixo. Para o tipo, selecione Opções predefinidas e adicione três opções, Não Iniciado, Em Andamento e Concluído
Na guia Atribuições, selecione Obrigatório para APIs. Selecione Não aplicável para Implantações e Ambientes
Selecione Avançar
Um esquema de metadados JSON para suas APIs agora está disponível para exibição, edição e download. Para exibir, selecione Exibir esquema de metadados e selecione APIs na lista suspensa.
Isso abre um modal à direita com detalhes de metadados, que incluem propriedades internas do Centro de API, como LifecycleStage, Name, Description, TermsOfService, entre outras. Se você rolar até a parte inferior do arquivo, verá os metadados personalizados adicionados nas etapas anteriores, conforme mostrado abaixo.
Observação
Você pode adicionar e editar propriedades no esquema a qualquer momento e aplicá-las instantaneamente a todas as APIs no Centro de API
Crie um novo esquema de metadados executando o seguinte comando para definir:
- O nome e metadados como aprovador de api
- de esquema com tipo de propriedade como de cadeia de caracteres e título como aprovador de API
- atribuições como necessárias para apis enquanto opcionais para Environment e Deployment
az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Repita a mesma etapas para:
- Nome do de metadados como voltado para o público
- esquema com tipo de propriedade como booliano e título como depúblico voltado para o público
- atribuições como necessárias para apis enquanto opcionais para Environment e Deployment
Executando o seguinte comando:
az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Por fim, repita as mesmas etapas para:
- Os metadados nome como de revisão de conformidade
- Esquema com tipo de propriedade como String e título como Compliance Review
- atribuições como necessárias para apis enquanto opcionais para Environment e Deployment
Executando o seguinte comando:
az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Você pode executar o comando a seguir para exibir uma lista de todos os metadados definidos no Centro de API.
az apic metadata list -g <resource-group-name> -n <api-center-name>
Observação
Você pode adicionar e editar propriedades no esquema a qualquer momento e aplicá-las instantaneamente a todas as APIs no Centro de API
Observação
No momento, não há suporte para essa ação no VS Code. Crie um usando a CLI do Azure ou o portal do Azure.
Etapa 3: Adicionar APIs ao inventário
A organização Contoso gostaria de recomendar conferências técnicas para suas equipes de engenharia como parte do mecanismo de qualificação interna deles. Adicionaremos uma API de Conferência com palestrantes, sessões e tópicos.
URL da API de conferência: https://bigconference.azurewebsites.net/
Para as etapas a seguir, você pode copiar a definição de OpenAPI do site acima e salvá-la como um arquivo JSON em seu computador local. Ou substitua uma definição de API diferente ao adicionar uma API ao inventário.
No portal, navegue até seu centro de API.
No menu à esquerda, selecione Ativos > APIs > + Registrar API.
Na página Registrar API, adicione as informações a seguir, necessárias para a API. Você verá as propriedades de metadados personalizadas de Aprovador de API, *Voltado para o público e de revisão de conformidade que você definiu nas etapas anteriores na parte inferior da página.
Para exibir a API criada, no menu à esquerda, selecione Ativos > APIs > API de Conferência.
A guia Visão geral fornece uma exibição da configuração da API. Expanda Detalhes para ver e editar informações adicionais, como implantações e versão de API (não temos implantações neste momento).
Normalmente, você deseja adicionar uma definição de API para sua versão de API e o Centro de API dá suporte a formatos de especificação de texto, incluindo OpenAPI 2, OpenAPI 3 para REST.
Para adicionar uma Definição,
- No menu à esquerda, selecione Ativos > APIs > Selecione sua API (API de Conferência).
- Expanda Detalhes e selecione Versões.
- Selecione sua versão (v1) e expanda Detalhes.
- Em detalhes, selecione Definições > Adicionar definição.
Você pode usar a extensão do Centro de API do Azure para Visual Studio Code para registrar uma API em sua instância de API.
Etapa 1: Instale a extensão
Etapa 2: Abra o palete de comando, 'Ctrl + Shift + P' e digite Centro de API: Registrar API
Siga os prompts para fornecer as seguintes informações para a sua API:
| Registrar API | Passo a passo |
|---|---|
| Selecione Serviço do Centro de API | Selecione sua instância do Centro de API |
| Título da API | Insira o nome da API (API de Conferência) |
| Tipo de API | REST |
| Título da versão da API | Insira um nome de versão para sua API (v1) |
| Ciclo de vida da versão da API | Selecione um ciclo de vida na lista suspensa (Desenvolvimento) |
| Título de definição de API | Insira um nome para sua definição (Definição de API de Conferência) |
| Nome de Especificação da API | Selecione uma especificação na lista suspensa (OpenAPI 2) |
| Selecione Arquivo de Definição de API a ser Importado | Navegue e selecione o arquivo de definição no armazenamento |
Atualize a guia de extensão do Centro de API e sua API recém-criada aparece na respectiva instância/recurso de APIC.
Use o seguinte comando para criar uma API, passando o seguinte:
- Exemplo do grupo de recursos -g. Contoso
- Exemplo de nome de centro de serviço de API -n. contoso-api-center
- Exemplo de título --title. API de Conferência
- Exemplo de ID da API --api-id. conference-api
- Exemplo de tipo --type. REST
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST
Crie uma versão da API usando o seguinte comando, passando o seguinte:
- Exemplo do grupo de recursos -g. contoso
- Exemplo de nome de centro de serviço de API -n. contoso-apis
- Exemplo de ID da API --api-id. conference-api
- Exemplo de título --title. v1.2.2
- Exemplo de ID da versão --version-id. 2024-07-03
- Exemplo do estágio do ciclo de vida --lifecycle-stage. design
az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design
Você também pode adicionar uma definição de API para sua versão de API; o Centro de API dá suporte a formatos de especificação de texto que incluem OpenAPI 2 e OpenAPI 3 para REST.
Para adicionar uma Definição, use o seguinte comando, passando:
- Exemplo do grupo de recursos -g. contoso
- Exemplo de nome de centro de serviço de API -n. contoso-apis
- Exemplo de ID da API --api-id. conference-api
- Exemplo de ID da versão --version-id. 2024-07-03
- Exemplo de título --title. OpenAPI
- Exemplo de ID de definição --definition-id. openapi
az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi
Para importar um arquivo de definição OpenAPI de uma URL, use o comando az apic api definition import-specification. Exemplo: https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples
az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'
Etapa 4: Adicionar implantações e ambientes
Ambientes
Um ambiente (Desenvolvimento, Teste, Preparo ou Produção) representa um local em que um runtime de API é implantado. Os engenheiros da plataforma de API da Contoso definem dois ambientes - teste e produção - em sua instância do API Center para gerenciar e rastrear diferentes tempos de execução de API em sua organização.
Para criar um ambiente,
No menu à esquerda, selecione Ativos > Ambientes > + Novo ambiente.
Adicione as informações a seguir.
Selecione Criar.
Repita as mesmas etapas para o Ambiente de produção.
Para criar um ambiente, execute o seguinte comando da CLI
az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing
Repita o mesmo para o ambiente de produção.
az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production
Observação
No momento, a criação de ambientes não é compatível com o VS Code. Use a CLI do Azure ou a opção do portal do Azure para esta etapa.
Implantações
Um local exclusivo (endereço) para os usuários interagirem com sua API é fornecido para cada runtime de API em um determinado ambiente. Esse local é chamado de implantação e apenas uma versão da API pode ter duas implantações: uma de preparo e uma de produção.
A Contoso tem uma API, a API de Conferência, que associamos aos ambientes que criamos.
No portal, navegue até seu centro de API.
No menu à esquerda, selecione APIs e selecione uma API, por exemplo, a API de Conferência.
Na página de API de Conferência, expanda Detalhes > Implantações > + Adicionar implantação.
Adicione as seguintes informações:
a. Selecione Testes da Contoso na lista suspensa para o campo Ambiente.
b. Para a definição, clique em Selecionar, escolha a versão da API v1 na lista suspensa e selecione a definição que você adicionou anteriormente. Clique em Selecionar.
c. Depois de adicionar a definição com êxito, adicione uma URL de runtime base que será específica para a API no ambiente selecionado.
Para criar uma implantação e associá-la ao ambiente que criamos na etapa acima, execute o seguinte comando da CLI
az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'
Observação
No momento, a criação de ambientes não é compatível com o VS Code. Use a CLI do Azure ou a opção do portal do Azure para esta etapa.