Introdução ao Centro de API
Neste exercício, irá:
Crie um serviço da Central de APIs.
Defina propriedades de metadados.
Adicione APIs ao seu Centro de APIs.
Adicione implantações e ambientes.
Pré-requisitos
Para começar a gerenciar suas APIs por meio do Centro de APIs, você precisa:
- Uma subscrição do Azure.
- O provedor de recursos Microsoft.ApiCenter registrado em sua assinatura.
- Pelo menos uma atribuição de função de Colaborador ou permissões equivalentes na assinatura do Azure.
Nota
Se ainda não o fez, tem de registar o fornecedor de recursos Microsoft.ApiCenter na sua subscrição.
- Inicie sessão no portal do Azure.
- Introduza Subscrições na barra de pesquisa.
- Selecione a assinatura onde você deseja criar a Central de APIs.
- No menu à esquerda, em Recursos, selecione Provedores de recursos.
- Procure Microsoft.ApiCenter na lista de fornecedores de recursos. Se não estiver registado, selecione Registar.
Etapa 1: Criar um serviço da Central de APIs
Insira Centros de API na barra de pesquisa.
Selecione + Criar.
Na guia Noções básicas, selecione ou insira as seguintes configurações:
a. Selecione a subscrição do Azure.
b. Selecione um grupo de recursos existente ou selecione Novo para criar um novo.
c. Insira um Nome para o seu centro de API. Ele deve ser exclusivo na região onde você está criando seu centro de API.
d. Em Região, selecione uma das regiões disponíveis para o Centro de APIs.
e. Para o plano de preços, selecione Avaliação gratuita (US$ 0 por 90 dias).
f. Selecione Rever + criar.
h. Após a conclusão da validação, selecione Criar.
Após a implantação, seu centro de API está pronto para uso!
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
Nota
Se ainda não o fez, tem de registar o fornecedor de recursos Microsoft.ApiCenter na sua subscrição.
Execute o seguinte comando para registrar o provedor de recursos
az provider register –namespace Microsoft.ApiCenter
Etapa 1: Criar um serviço da Central de APIs
Crie um grupo de recursos executando o seguinte comando passando:
- nome do grupo de recursos --name Exemplo. Contoso
- location --location Exemplo. Páscoa
az group create –-name contoso –-location eastus
Nota
az apic comandos exigem a extensão apic-extension Azure CLI. Se você não tiver usado comandos az apic , a extensão será instalada dinamicamente quando você executar seu primeiro comando az apic , ou você pode instalar a extensão manualmente. Saiba mais sobre as extensões da CLI do Azure.
Crie uma Central de API executando o seguinte comando, passando:
- Nome do serviço do centro de API -n Exemplo. contoso-apis
- Grupo de recursos -g Exemplo. Contoso
- localização --l Exemplo. Páscoa
az apic create -n contoso-apis -g contoso -l eastus
Nota
Por padrão, o Centro de API será criado sob o nível de preço Gratuito.
Nota
Atualmente, 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 APIs usa propriedades de metadados para organizar as APIs em seu inventário e habilitar operações como filtragem, pesquisa, etc.
Nota
Não inclua informações confidenciais, confidenciais ou pessoais nos títulos/nomes das propriedades de metadados.
A Contoso, como muitas outras organizações, gostaria que todas as suas APIs passassem por um aprovador antes de ficarem disponíveis para uso e garantir que uma análise de conformidade seja conduzida para todas as APIs. A organização também tem APIs voltadas para o público e aquelas construídas exclusivamente para uso interno. Para impor isso em escala em todas as APIs, adicionamos três propriedades de metadados personalizadas:
- Aprovador de API do tipo String
- Revisão da conformidade do tipo Opções predefinidas
- Face pública do tipo booleano
No menu à esquerda, selecione Metadados de > ativos > + Novos metadados.
Na guia Detalhes, insira 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 String e selecione Next
Na guia Atribuições, selecione Necessário para APIs. Selecione Opcional para implantações e ambientes. Selecione Seguinte
Selecione Criar
Repita as mesmas etapas para a propriedade voltada para o público, conforme mostrado na imagem abaixo. Para tipo, selecione Boolean
Na guia Atribuições, selecione Necessário para APIs. Selecione Não aplicável para implantações e ambientes. Selecione Seguinte
Selecione Criar
Repita as mesmas etapas para a propriedade Compliance-review , conforme mostrado na imagem abaixo. Para o tipo, selecione Opções predefinidas e adicione 3 opções, Não iniciado, Em andamento e Concluído
Na guia Atribuições, selecione Necessário para APIs. Selecione Não aplicável para implantações e ambientes
Selecione Seguinte
Um esquema de metadados JSON para suas APIs agora está disponível para visualizaçã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 outros. Se você rolar até a parte inferior do arquivo, verá os metadados personalizados que adicionou nas etapas anteriores, conforme mostrado abaixo.
Nota
Você pode adicionar e editar propriedades no esquema a qualquer momento e aplicá-las instantaneamente a todas as APIs em sua Central de APIs
Crie um novo esquema de metadados executando o seguinte comando, para definir o:
- Nome de metadados como api-approver
- Esquema com tipo de propriedade como String e título como API Approver
- Atribuições conforme necessário para APIs enquanto opcionais para Ambiente e Implantação
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 os mesmos passos para:
- Nome dos metadados como voltado para o público
- Esquema com tipo de propriedade como booleano e título como voltado para o público
- Atribuições conforme necessário para APIs enquanto opcionais para Ambiente e Implantação
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 os mesmos passos para:
- Nome dos metadados como revisão de conformidade
- Esquema com tipo de propriedade como String e title como Revisão de conformidade
- Atribuições conforme necessário para APIs enquanto opcionais para Ambiente e Implantação
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 seguinte comando para exibir uma lista de todos os metadados definidos em sua Central de APIs.
az apic metadata list -g <resource-group-name> -n <api-center-name>
Nota
Você pode adicionar e editar propriedades no esquema a qualquer momento e aplicá-las instantaneamente a todas as APIs em sua Central de APIs
Nota
Esta ação não é suportada atualmente 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 da Contoso gostaria de recomendar conferências técnicas para suas equipes de engenharia como parte de sua unidade de qualificação interna. 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 sua máquina local. Ou substitua uma definição de API diferente ao adicionar uma API ao inventário.
No portal, navegue até o centro de APIs.
No menu à esquerda, selecione APIs de ativos > > + API de registro.
Na página Registrar API, adicione as seguintes informações necessárias para a API. Você verá as propriedades personalizadas do Aprovador de API, *Voltadas para o público e de revisão de conformidade que você definiu nas etapas anteriores na parte inferior da página.
Para visualizar a API criada, no menu à esquerda, selecione API de conferência de APIs > de ativos>.
A guia Visão geral fornece uma visão da configuração da API. Expanda Detalhes para ver e editar informações adicionais, como versão da API e implantações (não temos implantações no momento).
Normalmente, você gostaria de adicionar uma definição de API para sua versão de API e o Centro de API suporta formatos de especificação de texto, incluindo OpenAPI 2, OpenAPI 3 para REST.
Para adicionar uma definição,
- No menu à esquerda, selecione APIs > de ativos > 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: Instalar a extensão
Passo 2: Abra o comando palete, 'Ctrl + Shift + P' e digite API Center: Register API
Siga as instruções para fornecer as seguintes informações para sua API:
| Registrar API | Passo a passo |
|---|---|
| Selecionar Serviço do Centro de API | Selecione sua instância do Centro de API |
| Título da API | Insira o nome da sua 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 da definição da API | Insira um nome para sua definição (Definição da API de conferência) |
| Nome da especificação da API | Selecione uma especificação na lista suspensa (OpenAPI 2) |
| Selecione o arquivo de definição de API a ser importado | Procure e selecione o arquivo de definição do seu armazenamento |
Atualize a guia de extensão do Centro de API e sua API recém-criada aparecerá na respetiva instância/recurso APIC.
Use o seguinte comando para criar uma nova API, passando a:
- Grupo de recursos -g Exemplo. Contoso
- Nome do serviço do centro de API -n Exemplo. contoso-api-center
- Título --título Exemplo. API de conferência
- API ID --api-id Exemplo. Conferência-API
- Digite --type Exemplo. 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:
- Grupo de recursos -g Exemplo. Contoso
- Nome do serviço do centro de API -n Exemplo. contoso-apis
- API ID --api-id Exemplo. Conferência-API
- Título --título Exemplo. v1.2.2
- ID da versão --version-id Exemplo. 2024-07-03
- Estágio do ciclo de vida --Exemplo do estágio do ciclo de vida. Desenho
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 e o Centro de API suporta formatos de especificação de texto, incluindo OpenAPI 2, OpenAPI 3 para REST.
Para adicionar uma Definição, use o seguinte comando, passando:
- Grupo de recursos -g Exemplo. Contoso
- Nome do serviço do centro de API -n Exemplo. contoso-apis
- API ID --api-id Exemplo. Conferência-API
- ID da versão --version-id Exemplo. 2024-07-03
- Título --título Exemplo. OpenAPI
- ID da definição --definition-id Exemplo. 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 para importar . 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 onde um tempo de execução da API é implantado. Os engenheiros da Plataforma de API da Contoso definem dois ambientes – Teste e produção, em sua instância do Centro de API para gerenciar e rastrear diferentes tempos de execução de API em sua organização.
Para criar um ambiente,
No menu à esquerda, selecione Assets > Environments > + New environment.
Adicione as seguintes informações.
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
Nota
Atualmente, a criação de ambientes não é suportada no VS Code. Use a CLI do Azure ou a opção do portal do Azure para esta etapa.
Implementações
Um local exclusivo (endereço) para os usuários interagirem com sua API é fornecido para cada tempo de execução da API em um determinado ambiente. Esse local é chamado de implantação, e uma única versão de API pode ter duas implantações - uma implantação de preparação e uma implantação de produção.
A Contoso tem uma API, a API de Conferência, que associamos aos ambientes que criamos.
No portal, navegue até o centro de APIs.
No menu à esquerda, selecione APIs e, em seguida, selecione uma API, por exemplo, a API de conferência.
Na página API de conferência, expanda Detalhes > Implantações > + Adicionar implantação.
Adicione as seguintes informações:
a. Selecione Contoso Testing na lista suspensa do 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 adicionada anteriormente. Clique em Selecionar.
c. Depois de adicionar com êxito a definição, adicione uma URL de tempo de execução 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/"]}'
Nota
Atualmente, não há suporte para a criação de implantações no VS Code. Use a CLI do Azure ou a opção do portal do Azure para esta etapa.