Apresentando a API de Conectores no WordPress 7.0

O WordPress 7.0 apresenta a API de Conectores, uma nova estrutura para registrar e gerenciar conexões com serviços externos. O foco inicial está nos provedores de IA, oferecendo ao WordPress uma forma padronizada de gerenciar chaves de API, descobrir provedores e configurar serviços de IA na interface administrativa.

Este post explica o que a API de Conectores faz, como ela funciona internamente e o que os desenvolvedores de plugins precisam saber.

Sumário

• O que é um conector?
• Como os provedores de IA são descobertos automaticamente
• A tela de administração Configurações > Conectores
• Autenticação e gerenciamento de chaves de API
• Funções públicas da API
• Sobrescrita de metadados de conectores
• O ciclo de vida da inicialização
• Próximos passos

O que é um conector?

Um conector representa uma conexão com um serviço externo. Cada conector carrega metadados padronizados: um nome de exibição, uma descrição, um logotipo, uma configuração de autenticação e uma associação opcional a um plugin do WordPress.org. O sistema atualmente se concentra em provedores que autenticam com uma chave de API, mas a arquitetura foi projetada para oferecer suporte a outros tipos de conectores em lançamentos futuros.

O WordPress 7.0 vem com três conectores em destaque, Anthropic, Google e OpenAI, acessíveis pela nova tela Configurações → Conectores, tornando a instalação fluida.

Cada conector é armazenado como um array associativo com a seguinte estrutura:

array(
    'name'           => 'Anthropic',
    'description'    => 'Text generation with Claude.',
    'logo_url'       => 'https://example.com/anthropic-logo.svg',
    'type'           => 'ai_provider',
    'authentication' => array(
        'method'          => 'api_key',
        'credentials_url' => 'https://platform.claude.com/settings/keys',
        'setting_name'    => 'connectors_ai_anthropic_api_key',
    ),
    'plugin'         => array(
        'file' => 'ai-provider-for-anthropic/plugin.php',
    ),
)

Como os provedores de IA são descobertos automaticamente

Se você está criando um plugin de provedor de IA que se integra ao WP AI Client, não precisa registrar um conector manualmente. A API de Conectores identifica automaticamente os provedores com base no registro padrão do WP AI Client e cria conectores com os metadados corretos.

Veja o que acontece durante a inicialização:

1. Os conectores nativos (Anthropic, Google, OpenAI) são registrados com padrões definidos diretamente no código.
2. O sistema consulta AiClient::defaultRegistry() para obter todos os provedores registrados.
3. Para cada provedor, os metadados (nome, descrição, logotipo, método de autenticação) são mesclados aos padrões, com os valores do registro do provedor tendo precedência.
4. A ação wp_connectors_init é disparada para que plugins possam sobrescrever metadados ou registrar conectores adicionais.

Em resumo: se o seu plugin de provedor de IA se registra no WP AI Client, o conector é criado para você. Nenhum código adicional é necessário.

A tela de administração Configurações > Conectores

Os conectores registrados aparecem em uma nova tela de administração: Configurações > Conectores. A tela renderiza cada conector como um cartão, e os dados do registro determinam o que é exibido:

• name, description e logo_url são exibidos no cartão.
• plugin.file: o valor é o caminho do arquivo principal do plugin em relação ao diretório de plugins (por exemplo, akismet/akismet.php ou hello.php). A tela usa esse valor para verificar se o plugin associado está instalado e ativo, e mostra o botão de ação apropriado.
• authentication.credentials_url é renderizado como um link que direciona os usuários ao site do provedor para obter credenciais de API.
• Para conectores api_key, a tela mostra a origem atual da chave (variável de ambiente, constante PHP ou banco de dados) e o status da conexão.

Conectores com outros métodos de autenticação são armazenados no registro PHP e expostos pelos dados do módulo de script, mas atualmente, exigem um registro de JavaScript no lado do cliente para uma interface personalizada no frontend.

Autenticação e gerenciamento de chaves de API

Os conectores oferecem suporte a dois métodos de autenticação:

• api_key: exige uma chave de API, que pode ser fornecida por variável de ambiente, constante PHP ou banco de dados (verificadas nessa ordem).
• none: nenhuma autenticação é necessária.

O método de autenticação (api_key ou none) é determinado pelos metadados de autenticação registrados com o conector. Para provedores que usam api_key, um nome de configuração no banco de dados é gerado automaticamente usando o padrão connectors_{$provider_type}_{$provider_id}_api_key. Também é possível definir um nome personalizado usando a propriedade setting_name. As chaves de API armazenadas no banco de dados não são criptografadas, mas são mascaradas na interface do usuário.

A criptografia está sendo explorada em um ticket de acompanhamento: #64789.

Para provedores de IA, há uma convenção de nomenclatura específica para variáveis de ambiente e constantes PHP: {PROVIDER_ID}_API_KEY (por exemplo, o provedor anthropic é mapeado para ANTHROPIC_API_KEY). Para outros tipos de provedores, uma variável de ambiente (env_var_name) e uma constante PHP (constant_name) podem ser opcionalmente definidas com qualquer valor.

Prioridade da origem da chave de API

Para conectores api_key, o sistema procura um valor de configuração nesta ordem:

1. Variável de ambiente, por exemplo, ANTHROPIC_API_KEY
2. Constante PHP, por exemplo, define( 'ANTHROPIC_API_KEY', 'sk-...' );
3. Banco de dados, armazenado pela tela de administração, por exemplo, a configuração connectors_ai_anthropic_api_key

Funções públicas da API

A API de Conectores fornece três funções públicas para consultar o registro. Elas ficam disponíveis após init.

wp_is_connector_registered()

Verifica se um conector está registrado:

if ( wp_is_connector_registered( 'anthropic' ) ) {
    // The Anthropic connector is available.
}

wp_get_connector()

Recupera os dados de um único conector:

$connector = wp_get_connector( 'anthropic' );
if ( $connector ) {
    echo $connector['name']; // 'Anthropic'
}

Retorna um array associativo com as chaves: name, description, type, authentication e, opcionalmente, logo_url e plugin. Retorna null se o conector não estiver registrado.

wp_get_connectors()

Recupera todos os conectores registrados, indexados pelo ID do conector:

$connectors = wp_get_connectors();
foreach ( $connectors as $id => $connector ) {
    printf( '%s: %s', $connector['name'], $connector['description'] );
}

Sobrescrita de metadados de conectores

A ação wp_connectors_init é disparada depois que todos os conectores nativos e descobertos automaticamente foram registrados. Plugins podem usar esse hook para sobrescrever metadados em conectores existentes.

Como o registro rejeita IDs duplicados, a sobrescrita exige uma sequência para remover o conector do registro, modificar e registrar novamente:

add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) {
    if ( $registry->is_registered( 'anthropic' ) ) {
        $connector = $registry->unregister( 'anthropic' );
        $connector['description'] = __( 'Custom description for Anthropic.', 'my-plugin' );
        $registry->register( 'anthropic', $connector );
    }
} );

Pontos importantes sobre o padrão de sobrescrita:

• Sempre verifique is_registered() antes de chamar unregister(): chamar unregister() em um conector inexistente dispara um aviso _doing_it_wrong().
• unregister() retorna os dados do conector, que você pode modificar e passar de volta para register().
• IDs de conectores precisam corresponder ao padrão /^[a-z0-9_-]+$/ (somente letras minúsculas, números, sublinhados e hífens).

Métodos do registro

Dentro do callback de wp_connectors_init, a instância de WP_Connector_Registry fornece estes métodos:

Fora do callback de wp_connectors_init, use as funções públicas da API (wp_get_connector(), wp_get_connectors(), wp_is_connector_registered()) em vez de acessar o registro diretamente.

O ciclo de vida da inicialização

Entender a sequência de inicialização ajuda a decidir onde usar hooks:

Durante a ação init, _wp_connectors_init() é executada e:

• Cria o singleton de WP_Connector_Registry.
• Registra conectores nativos (Anthropic, Google, OpenAI) com padrões definidos diretamente no código.
• Descobre automaticamente provedores a partir do registro do WP AI Client e mescla seus metadados sobre os padrões.
• Dispara a ação wp_connectors_init, que é onde plugins sobrescrevem metadados ou registram conectores adicionais.

A ação wp_connectors_init é o único ponto de entrada compatível para modificar o registro. Tentar definir a instância do registro fora de init dispara um aviso _doing_it_wrong().

Próximos passos

A API de Conectores no WordPress 7.0 foi otimizada para provedores de IA, mas a arquitetura subjacente foi projetada para crescer. Atualmente, apenas conectores com autenticação api_key recebem o tratamento completo na interface de administração. O registro PHP já aceita qualquer tipo de conector, o que falta é a integração de frontend para conectores com mecanismos de autenticação diferentes.

Espera-se que lançamentos futuros:

• Expandam o suporte para outros métodos de autenticação além de api_key e none.
• Ofereçam mais integrações nativas de interface além de api_key.
• Forneçam uma API de registro JavaScript no lado do cliente para interfaces personalizadas de conectores.

Quando esses recursos estiverem disponíveis, a ação wp_connectors_init será o hook principal para registrar novos tipos de conectores.

Props a @jorgefilipecosta, @shaunandrews, @flixos90, @westonruter, @justlevine e outras pessoas por contribuírem para a tela de Conectores e para esta nota de desenvolvimento.

#7-0 #dev-notes #dev-notes-7-0